Introduction
Welcome to the Data360 Analyze REST API guide.
The Data360 Analyze REST API provides access to Data360 Analyze via third party applications, allowing you to log in and out of the application and create and manage scheduled runs of your data flows through the APIs.
This document is divided into a number of sections:
-
Conventions - Describes the Data360 Analyze API conventions and any variations from REST API conventions.
-
Definitions - Describes Data360 Analyze concepts that apply to all the API services.
-
Resources - Describes the API interfaces in detail.
-
Tutorials - Provides guidance for implementing common use cases.
Revision Information
The Simple Scheduled Tasks API is updated to v4 and is not backward-compatible with v3. Simple Scheduled Tasks API v3 is deprecated.
Note the following changes in the Simple Scheduled Tasks API:
-
The map of run properties is replaced by a
runPropertySet
object which contains a list of run properties. -
dataFlowLocator
is used to identify the scheduled data flow. This replacessearchPathSet
anddataFlowId
-
The Ad-hoc Run Of a Simple Scheduled Task API (
run-now
) returns theexecutionPlanStateLocator
which identifies the run status. It can be used with the Execution Plan States API to query the status of the run. -
It is now possible to specify follow up actions to take when a scheduled data flow succeeds or fails. For example it is possible to execute another data flow or send an email notification. Email notification settings must be configured in the UI.
Data360 Analyze REST API Conventions
HTTP verbs
Data360 Analyze REST API Service tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.
Verb | Usage |
---|---|
|
Used to retrieve a resource. |
|
Used to create a new resource. |
|
Used to update an existing resource, full updates only. |
|
Used to delete an existing resource. |
There are some exceptions to this pattern where actions are specified in the url. For example:
..api/v3/simple-scheduled-tasks/run-now/object:!tenant:defaultTenant~workspace:workspace~simple-scheduled-task:simple-scheduled-task-id
In general this occurs when the action does not easily map to an HTTP verb on the resource.
HTTP Status Codes
Data360 Analyze REST API returns the following HTTP Status Codes:
HTTP Code | Meaning | Response Body |
---|---|---|
|
Success. |
Depends on requested resource. |
|
Still processing. |
Body containing the asynchronous job id. |
|
Request error. |
Body containing the error information. See errors. |
|
Authentication required and failed. |
Request and Response Body Formats
All request and response bodies are in JSON format unless the resource type is binary in nature. Attribute names use camelCase.
Filtering lists
Some lists can be filtered by resource attributes. Data360 Analyze uses the FIQL format for the filter parameter.
Filter values containing spaces should be surrounded by quotes e.g. filter=name=='data flow name'
|
Specifying fields to return
When requesting resources it is possible to specify which sets of fields are returned:
-
object
- return the object attributes -
metadata
- return the metadata for the object. One or more sets can be retrieved in the same response e.g. specifyingfields=object, metadata
will return the object attributes and the metadata.
If the fields
parameter is not specified then only the object attributes are returned.
Definitions
Data360 Analyze Content Repository
The Data360 Analyze Content Repository (DCR) stores Data360 Analyze object resources. It has a hierarchical structure.
The tenant resource is at the root of the hierarchy. It contains all resources for an enterprise. For a single-tenant installation the tenant name defaults to defaultTenant .
|
Object Resources
Object Resource Locator
A Data360 Analyze object resource is uniquely identified by an Object Resource Locator (ORL). The Object Resource Locator also indicates the path to the resource in the DCR hierarchy. The Object Resource Locator format is as follows:
object:[!][<container-type>:<container-identity>~]*<type> :<identity>
where:
-
object: indicates that the resource locator identifies a data object.
-
! indicates that the resource locator is absolute i.e. it describes the complete hierarchy.
-
<type> is the resource type.
-
<identity> is the unique resource identity.
-
~ is the separator between levels in the hierarchy.
-
<container-type>:<container-identity> is the type and identifier of the resource container. There can be zero or more containers in the hierarchy.
Here are some examples:
Object Resource Locator | Description |
---|---|
object:!tenant:defaultTenant |
The default tenant. |
object:!tenant:defaultTenant~user:user-id |
A user contained in the default tenant. |
object:!tenant:defaultTenant~workspace:workspace-id |
A workspace contained in the default tenant. |
object:!tenant:defaultTenant~workspace:workspace-id~simple-scheduled-task:simple-scheduled-task-id |
A scheduled task contained in the workspace identified by workspace-id. |
Object Resource Metadata
Each resource has the following metadata associated with it:
-
Creation date
-
Created by user id
-
Created by user name
-
Last modified date
-
Last modified by user id
-
Last modified by user name
-
Resource type
-
Resource identity
-
Object resource locator
-
Container object resource locator
Errors
With the exception of the 401 HTTP Status Code returned for authentication failure, the Data360 Analyze REST API will always return a 400 HTTP Status Code to indicate errors. The response should be further parsed to ascertain the error details.
In addition to a descriptive error message, an error code and arguments are returned which can be internationalized as required.
Error Message Format
Path | Type | Description |
---|---|---|
|
|
The status of the response. It will be |
|
|
An array of errors. A response may report multiple errors. |
|
|
The locale used to render the message. |
|
|
The error code uniquely identifies the error type. |
|
|
An array of messages associated with the error. |
|
|
An array of argument values related to the message. |
|
|
The value of an argument. |
|
|
The message key uniquely identifies the message associated with the error. |
|
|
The error message rendered in a readable format. |
Example
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 413
{
"status" : "ERROR",
"errors" : [ {
"errorCode" : "lae.collection.objectNotFoundError",
"messages" : [ {
"message" : "The object requested 'object:!tenant:defaultTenant~user:nouser' cannot be found.",
"messageKey" : "lae.collection.objectNotFoundError",
"arguments" : [ {
"value" : "object:!tenant:defaultTenant~user:nouser"
} ]
} ],
"locale" : "en_US"
} ]
}
Resources
Login Flows
When the client is authenticating it must go through a series of steps called login flows. The Login Flows API returns the entry point URIs for the available login flows. REST API clients should choose the rest
entry point.
Get Available Login Flows
A GET
request is used to retrieve the available login flows.
Request parameters
None
Request fields
None
Response fields
Path | Type | Description |
---|---|---|
|
|
The name of the flow. |
|
|
The URI to call to initiate the flow. |
|
|
HTTP Status Code. |
Example request
GET /api/v3/login/flows HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 152
{"status":"OK","data":{"flows":[{"entryPointUri":"/login/ui/initial","name":"ui"},{"entryPointUri":"/api/v3/login/rest/tenant/methods","name":"rest"}]}}
Tenant Methods
When Data360 Analyze is configured to support multiple tenants, the client must identify which tenant it belongs to before authenticating. The Tenant Methods API returns a set of tenant methods that may be used to identify the tenant. The order of the methods in the response indicates the priority in which they should be tried.
Note that Data360 Analyze is most commonly configured to support a single tenant. In this case the tenant is always identified using the tenant locator object:!tenant:defaultTenant
.
Get Tenant Methods
A GET
request is used to retrieve the tenant methods.
Request parameters
None
Request fields
None
Response fields
Path | Type | Description |
---|---|---|
|
|
The name of the tenant method. |
|
|
The URI of the tenant method. |
|
|
HTTP Status Code. |
Example request
GET /api/v3/login/rest/tenant/methods HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 68
{"status":"OK","data":{"methods":[{"name":"automatic","uri":null}]}}
Resolve Tenant Automatically
Using the Automatic Tenant Resolver, Data360 Analyze will attempt to identify the tenant based on the system configuration.
A GET
request is used to resolve the tenant automatically.
Request parameters
None
Request fields
None
Response fields
Path | Type | Description |
---|---|---|
|
|
The tenant that the authenticating user belongs to. |
|
|
The URI to retrieve the authentication methods supported by the tenant. |
|
|
HTTP Status Code. |
Example request
GET /api/v3/login/rest/tenant/automatic HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 181
{"status":"OK","data":{"tenantLocator":"object:!tenant:defaultTenant","tenantAuthMethodsUri":"/api/v3/login/rest/authentication/methods?tenantLocator=object:!tenant:defaultTenant"}}
User Session
To use the Data360 Analyze REST APIs, you must first acquire an authentication token. This authentication token is then used in every subsequent request to authenticate access. We recommend that you release the token when it is no longer in use, as the REST API user will use one of the allocated user-based licenses.
The authentication can be passed in subsequent requests as a header parameter or query parameter named "ltk".
Get Supported Authentication Methods
Before authenticating, the client should identify the authentication methods supported by its tenant. The available authenticated methods are configured in the application and may be restricted by license.
A GET
request is used to retrieve the supported authentication methods.
Request parameters
Parameter | Description |
---|---|
|
Tenant Locator |
Response fields
Path | Type | Description |
---|---|---|
|
|
The name of the method. |
|
|
URI to call to initialisze the session. |
|
|
URI to call to renew the authentication token for the session to prevent timeout. |
|
|
URI to call to unlock the session after locking due to timeout. |
|
|
URI to call to logout of the session. |
|
|
HTTP Status Code. |
Example request
GET /api/v3/login/rest/authentication/methods?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 359
{"status":"OK","data":{"methods":[{"logoutUri":"/api/v3/logout/rest/authentication/username-password/initial","renewUri":"/api/v3/login/rest/authentication/username-password/renew","unlockUri":"/api/v3/login/rest/authentication/username-password/unlock","initialUri":"/api/v3/login/rest/authentication/username-password/initial","name":"username-password"}]}}
Acquire an authentication token using Username Password Authentication
A POST
request is used to acquire the token.
Request parameters
Parameter | Description |
---|---|
|
Tenant Locator |
Request fields
Path | Type | Description |
---|---|---|
|
|
The username. |
|
|
The password. |
Response fields
Path | Type | Description |
---|---|---|
|
|
The authentication token. |
|
|
URI to call to unlock the session after locking due to timeout. |
|
|
URI to call to renew the authentication token for the session to prevent timeout. |
|
|
URI to call to logout of the session. |
|
|
HTTP Status Code. |
Example request
POST /api/v3/login/rest/authentication/username-password/initial?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
Content-Length: 50
Host: localhost:8080
{ "username":"username","password":"userpassword"}
Example response
HTTP/1.1 200 OK
Set-Cookie: analyze_ltk=returnedToken; Path=/; Domain=localhost; Max-Age=28800; Expires=Wed, 31 May 2023 11:10:09 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json
Content-Length: 267
{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/username-password/unlock","renewUri":"/api/v3/login/rest/authentication/username-password/renew","logoutUri":"/api/v3/logout/rest/authentication/username-password/initial"}}
Renew a token using Username Password Authentication
A session token has a finite lifespan. If the token has expired then it must be renewed. An error with the error code lae.security.authentication.sessionTimeout
will be returned for any API call made using the expired token.
A `POST` request is used to renew the token.
Request headers
Name | Description |
---|---|
|
token to renew |
Request parameters
Parameter | Description |
---|---|
|
Tenant Locator |
Request fields
Path | Type | Description |
---|---|---|
|
|
The username. |
|
|
The password. |
Response fields
Path | Type | Description |
---|---|---|
|
|
The authentication token. |
|
|
URI to call to unlock the session after locking due to timeout. |
|
|
URI to call to renew the authentication token for the session to prevent timeout. |
|
|
URI to call to logout of the session. |
|
|
HTTP Status Code. |
Example request
POST /api/v3/login/rest/authentication/username-password/renew?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
ltk: tokenToRenew
Content-Length: 50
Host: localhost:8080
{ "username":"username","password":"userpassword"}
Example response
HTTP/1.1 200 OK
Set-Cookie: analyze_ltk=returnedToken; Path=/; Domain=localhost; Max-Age=28800; Expires=Wed, 31 May 2023 11:10:09 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json
Content-Length: 267
{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/username-password/unlock","renewUri":"/api/v3/login/rest/authentication/username-password/renew","logoutUri":"/api/v3/logout/rest/authentication/username-password/initial"}}
Unlock a session using Username Password Authentication
If the Session Timeout property is configured then the session will be locked after the specified period of inactivity. An error with the error code lae.security.authentication.sessionLocked
will be returned for any API call made using the locked token.
A POST
request is used to unlock the session.
Request headers
Name | Description |
---|---|
|
token to unlock |
Request parameters
Parameter | Description |
---|---|
|
Tenant Locator |
Request fields
Path | Type | Description |
---|---|---|
|
|
The username. |
|
|
The password. |
Response fields
Path | Type | Description |
---|---|---|
|
|
The authentication token. |
|
|
URI to call to unlock the session after locking due to timeout. |
|
|
URI to call to renew the authentication token for the session to prevent timeout. |
|
|
URI to call to logout of the session. |
|
|
HTTP Status Code. |
Example request
POST /api/v3/login/rest/authentication/username-password/unlock?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
ltk: tokenToUnlock
Content-Length: 50
Host: localhost:8080
{ "username":"username","password":"userpassword"}
Example response
HTTP/1.1 200 OK
Set-Cookie: analyze_ltk=returnedToken; Path=/; Domain=localhost; Max-Age=28800; Expires=Wed, 31 May 2023 11:10:09 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json
Content-Length: 267
{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/username-password/unlock","renewUri":"/api/v3/login/rest/authentication/username-password/renew","logoutUri":"/api/v3/logout/rest/authentication/username-password/initial"}}
Release an authentication token using Username Password Authentication
A GET
request is used to release the token.
Request headers
Name | Description |
---|---|
|
token to logout |
Request fields
None
Response fields
Path | Type | Description |
---|---|---|
|
|
HTTP Status Code. |
Example request
GET /api/v3/logout/rest/authentication/username-password/initial HTTP/1.1
Content-Type: application/json;charset=UTF-8
ltk: tokenToLogout
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 15
{"status":"OK"}
Users
Get a specified user
GET
request returns the specified user.
Path Parameters
Parameter | Description |
---|---|
|
The object resource locator of the requested user. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
|
Specifies the fields to return in the response. One or more of |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested user. |
|
|
Status of the response. One of: |
|
|
The identity of the user. |
|
|
The name of the user. |
|
|
The first name of the user. |
|
|
The last name of the user. |
|
|
The email address of the user. |
|
|
Custom attributes associated with the user. |
|
|
The tenant the user belongs to. |
|
|
|
|
|
One of |
|
|
|
|
|
If user is imported then this will contain details relevant to the import. |
|
|
Metadata for the resource. |
|
|
The resource locator that uniquely identifies the resource. |
|
|
The userid of the user that created the resource. |
|
|
The username of the user that created the resource. |
|
|
Creation time of resource in ISO-8601 format. |
|
|
The userid of the user that last modified the resource. |
|
|
The username of the user that last modified the resource. |
|
|
Last modification time of resource in ISO-8601 format. |
|
|
The resource locator that uniquely identifies the container resource. |
|
|
The resource type. |
|
|
The resource id. |
|
|
True if the resource id is universally addressable. |
Example request
GET /api/v3/users/object:!tenant:defaultTenant~user:user-id?ltk=AUTHENTICATION_TOKEN&fields=object,metadata HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1238
{
"status" : "OK",
"data" : {
"metadata" : {
"createdByName" : "Created By User Name",
"modifiedByName" : "Modified By User Name",
"browsingMetadata" : {
"name" : "User Name",
"description" : "User Name"
},
"locator" : "object:!tenant:defaultTenant~user:user-id",
"containerLocator" : "object:!tenant:defaultTenant",
"createdBy" : "created-by-user-Id",
"createdOn" : "2023-05-31T03:10:09+0000",
"modifiedBy" : "modified-by-user-Id",
"modifiedOn" : "2023-05-31T03:10:09+0000",
"resourceId" : {
"objectType" : "user",
"objectId" : "user-id",
"universal" : false
},
"universalLocator" : null,
"universalContainerLocator" : null
},
"locator" : "object:!tenant:defaultTenant~user:user-id",
"object" : {
"id" : "user-id",
"tenant" : "defaultTenant",
"name" : "User Name",
"imported" : false,
"active" : true,
"state" : "ACTIVE",
"principalImportDetails" : null,
"attributes" : [ "user-attribute-1", "user-attribute-2" ],
"firstName" : "Firstname",
"lastName" : "Lastname",
"emailAddress" : "firstname.lastname@infogix.com"
}
}
}
Get a list of users
GET
request returns the list of users.
Path Parameters
None
Request Parameters
Parameter | Description |
---|---|
|
The container locator of the requested users. |
|
Specifies the fields to return in the response. One or more of |
|
An optional FIQL filter expression. Supports searching by the 'name' attribute. For example |
|
The authentication token. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested user. |
|
|
Status of the response. One of: |
|
|
The identity of the user. |
|
|
The name of the user. |
|
|
The first name of the user. |
|
|
The last name of the user. |
|
|
The email address of the user. |
|
|
Custom attributes associated with the user. |
|
|
The tenant the user belongs to. |
|
|
|
|
|
One of |
|
|
|
|
|
If user is imported then this will contain details relevant to the import. |
Example request
GET /api/v3/users?container=object:!tenant:defaultTenant~directory:workspace-id&fields=object&filter=name%3D%3D'User%20Name'<k=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1135
{
"status" : "OK",
"data" : {
"objects" : [ {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~user:user-id-001",
"object" : {
"id" : "user-id-001",
"tenant" : "defaultTenant",
"name" : "First User",
"imported" : false,
"active" : true,
"state" : "ACTIVE",
"principalImportDetails" : null,
"attributes" : [ "user-attribute-1", "user-attribute-2" ],
"firstName" : "Firstname",
"lastName" : "Lastname",
"emailAddress" : "firstname.lastname@infogix.com"
}
}, {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~user:user-id-002",
"object" : {
"id" : "user-id-002",
"tenant" : "defaultTenant",
"name" : "Second User",
"imported" : false,
"active" : true,
"state" : "ACTIVE",
"principalImportDetails" : null,
"attributes" : [ "user-attribute-1", "user-attribute-2" ],
"firstName" : "Firstname",
"lastName" : "Lastname",
"emailAddress" : "firstname.lastname@infogix.com"
}
} ]
}
}
User Preferences
Get the user preferences for a specified user
GET
request returns the user preferences for the specified user.
Path Parameters
Parameter | Description |
---|---|
|
The user locator for the user whose preferences are requested . |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
|
Specifies the fields to return in the response. One or more of |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested user preferences. |
|
|
Status of the response. One of: |
|
|
The identity of the user preference. |
|
|
The default search path set for the user. |
|
|
The user’s storage preferences. |
|
|
The object resource locator of the workspace where user generated artifacts are stored. |
|
|
The object resource locator of the workspace where temporal user generated artifacts are stored. This is reserved for system use. |
|
|
The identity of the user’s clipboard. This is reserved for system use. |
Example request
GET /api/v3/users/object:!tenant:defaultTenant~user:user-id/userpreferences?ltk=AUTHENTICATION_TOKEN&fields=object HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 644
{
"status" : "OK",
"data" : {
"objects" : [ {
"locator" : "object:!tenant:defaultTenant~user:user-id~userpreference:user-preference-id-001",
"object" : {
"id" : "user-preference-id-001",
"storagePreference" : {
"defaultWorkspace" : "object:!tenant:defaultTenant~workspace:771c6823-32c1-4c33-8408-eb3c06602996",
"temporaryWorkspace" : "object:!tenant:defaultTenant~workspace:1e94af54-352a-4327-a607-b3b65616033f",
"clipboardId" : "User Preference"
},
"defaultSearchPathSet" : "object:!tenant:defaultTenant~search-path-set:search-path-set-id"
}
} ]
}
}
Workspace
A workspace is a symbolic link to a directory.
The Public Documents directory, Data360 Nodes directory, and each user’s My Documents directory have workspace references. In addition each user’s temporary directory has a workspace reference. The temporary directory stores temporal data such as unsaved edit sessions. See user preferences for details about identifying a user’s workspaces.
In addition, system-generated workspaces are used to store core data such as Lavastorm nodes.
Get a list of workspaces
GET
request returns the list of workspaces.
Path Parameters
None
Request Parameters
Parameter | Description |
---|---|
|
The container locator of the requested workspaces. |
|
Specifies the fields to return in the response. One or more of |
|
An optional FIQL filter expression. Supports searching by the 'name' attribute. For example |
|
The authentication token. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested workspace. |
|
|
Status of the response. One of: |
|
|
The identity of the workspace. It must be unique and will be allocated if not specified at creation. |
|
|
The name of the workspace. |
|
|
The directory that the workspace references. |
Example request
GET /api/v3/workspaces?container=object:!tenant:defaultTenant~directory:workspace-id&fields=object&filter=name%3D%3D'Workspace%20Name'<k=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 761
{
"status" : "OK",
"data" : {
"objects" : [ {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~workspace:workspace-id-001",
"object" : {
"id" : "workspace-id-001",
"name" : "First Workspace",
"directory" : "object:!tenant:defaultTenant~directory:__Root__~directory:lavastorm~directory:directoryid",
"description" : null
}
}, {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~workspace:workspace-id-002",
"object" : {
"id" : "workspace-id-002",
"name" : "Second Workspace",
"directory" : "object:!tenant:defaultTenant~directory:__Root__~directory:lavastorm~directory:directoryid",
"description" : null
}
} ]
}
}
Directory
User artifacts such as data flows, library nodes, and scheduled tasks can be organized in directories.
Get a list of directories
GET
request returns the list of directories in the specified container. The container may be a directory, workspace or tenant. The response can be filtered by directory name.
Path Parameters
None
Request Parameters
Parameter | Description |
---|---|
|
The container locator of the requested directories. This can be a tenant, workspace or directory. |
|
Specifies the fields to return in the response. One or more of |
|
An optional FIQL filter expression. Supports searching by the 'name' attribute. For example |
|
The authentication token. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested directory. |
|
|
Status of the response. One of: |
|
|
The identity of the directory. It must be unique and will be allocated if not specified at creation. |
|
|
The name of the directory. |
|
|
Optional description of directory. |
Example request
GET /api/v3/directories?container=object:!tenant:defaultTenant~directory:workspace-id&fields=object&filter=name%3D%3D'Directory%20Name'<k=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 529
{
"status" : "OK",
"data" : {
"objects" : [ {
"locator" : "object:!tenant:defaultTenant~directory:directory-id-001",
"object" : {
"id" : "directory-id-001",
"name" : "First Directory",
"description" : "Description of Directory"
}
}, {
"locator" : "object:!tenant:defaultTenant~directory:directory-id-002",
"object" : {
"id" : "directory-id-002",
"name" : "Second Directory",
"description" : "Description of Directory"
}
} ]
}
}
Data flows
Dataflow Service is a RESTful service for listing data flows.
Get a list of data flows
GET
request returns the list of data flows.
Path Parameters
None
Request Parameters
Parameter | Description |
---|---|
|
The container locator of the requested data flows. |
|
Specifies the fields to return in the response. One or more of |
|
An optional FIQL filter expression. Supports searching by the 'name' attribute. For example |
|
The authentication token. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested data flow. |
|
|
Status of the response. One of: |
|
|
The identity of the data flow. |
|
|
The name of the data flow. |
|
|
Object resource locator identifying the search path that the dataflow uses to locate nodes it references. |
|
|
A map of run property definitions for the data flow. |
|
|
The run property name is used as the key. |
|
|
Name of the run property. This should be used when setting the run property value. |
|
|
The run property type. |
|
|
The visibility level of the run property. |
|
|
Indicates that the property is a run property. This is called |
|
|
Documentation for the run property. |
|
|
For property definitions of type |
|
|
Reserved for future use. |
|
|
Reserved for future use. |
|
|
Reserved for future use. |
|
|
Reserved for future use. |
|
|
Reserved for future use. |
|
|
Reserved for future use. |
Example request
GET /api/v3/dataflows?container=object:!tenant:defaultTenant~directory:workspace-id&fields=object&filter=name%3D%3D'Data%20Flow%20Name'<k=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1695
{
"status" : "OK",
"data" : {
"objects" : [ {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~dataflow:dataflow-id-001",
"object" : {
"id" : "dataflow-id-001",
"name" : "First Dataflow",
"searchPathSet" : "object:!tenant:defaultTenant~directory:workspace-id",
"runProperties" : {
"Run Property Name" : {
"name" : "Run Property Name",
"dataType" : "string",
"values" : [ ],
"validators" : [ ],
"documentation" : "A Run Property Definition",
"runParameter" : true,
"visibility" : 1,
"defaultSource" : "defaultSource",
"associatedInputs" : [ ],
"sources" : [ ],
"editors" : [ ],
"currentEditor" : "currentEditor"
}
}
}
}, {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~dataflow:dataflow-id-002",
"object" : {
"id" : "dataflow-id-002",
"name" : "Second Dataflow",
"searchPathSet" : "object:!tenant:defaultTenant~directory:workspace-id",
"runProperties" : {
"Run Property Name" : {
"name" : "Run Property Name",
"dataType" : "string",
"values" : [ ],
"validators" : [ ],
"documentation" : "A Run Property Definition",
"runParameter" : true,
"visibility" : 1,
"defaultSource" : "defaultSource",
"associatedInputs" : [ ],
"sources" : [ ],
"editors" : [ ],
"currentEditor" : "currentEditor"
}
}
}
} ]
}
}
Get data flow
GET
request returns a specified data flow.
Path Parameters
Parameter | Description |
---|---|
|
The object resource locator of the requested data flow. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
|
Specifies the fields to return in the response. One or more of |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested data flow. |
|
|
Status of the response. One of: |
|
|
The identity of the data flow. |
|
|
The name of the data flow. |
|
|
Object resource locator identifying the search path that the dataflow uses to locate nodes it references. |
|
|
A map of run property definitions for the data flow. |
|
|
The run property name is used as the key. |
|
|
Name of the run property. This should be used when setting the run property value. |
|
|
The run property type. |
|
|
The visibility level of the run property. |
|
|
Indicates that the property is a run property. This is called |
|
|
Documentation for the run property. |
|
|
For property definitions of type |
|
|
Reserved for future use. |
|
|
Reserved for future use. |
|
|
Reserved for future use. |
|
|
Reserved for future use. |
|
|
Reserved for future use. |
|
|
Reserved for future use. |
|
|
Metadata for the resource. |
|
|
The resource locator that uniquely identifies the resource. |
|
|
The userid of the user that created the resource. |
|
|
The username of the user that created the resource. |
|
|
Creation time of resource in ISO-8601 format. |
|
|
The userid of the user that last modified the resource. |
|
|
The username of the user that last modified the resource. |
|
|
Last modification time of resource in ISO-8601 format. |
|
|
The resource locator that uniquely identifies the container resource. |
|
|
The resource type. |
|
|
The resource id. |
|
|
True if the resource id is universally addressable. |
Example request
GET /api/v3/dataflows/object:!tenant:defaultTenant~directory:workspace-id~dataflow:dataflow-id?ltk=AUTHENTICATION_TOKEN&fields=metadata,object HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1479
{
"status" : "OK",
"data" : {
"metadata" : {
"createdByName" : "Created By User Name",
"modifiedByName" : "Modified By User Name",
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~dataflow:dataflow-id",
"containerLocator" : "object:!tenant:defaultTenant~directory:workspace-id",
"createdBy" : "created-by-user-Id",
"createdOn" : "2023-05-31T03:10:06+0000",
"modifiedBy" : "modified-by-user-Id",
"modifiedOn" : "2023-05-31T03:10:06+0000",
"resourceId" : {
"objectType" : "dataflow",
"objectId" : "dataflow-id",
"universal" : false
},
"universalLocator" : null,
"universalContainerLocator" : null
},
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~dataflow:dataflow-id",
"object" : {
"id" : "dataflow-id",
"name" : "Data flow",
"searchPathSet" : "object:!tenant:defaultTenant~directory:workspace-id",
"runProperties" : {
"Run Property Name" : {
"name" : "Run Property Name",
"dataType" : "string",
"values" : [ ],
"validators" : [ ],
"documentation" : "A Run Property Definition",
"runParameter" : true,
"visibility" : 1,
"defaultSource" : "defaultSource",
"associatedInputs" : [ ],
"sources" : [ ],
"editors" : [ ],
"currentEditor" : "currentEditor"
}
}
}
}
}
Simple Scheduled Task
Simple scheduled tasks are used to define schedules for the execution of data flows.
The results of the executed schedules are stored in execution plan states which are contained in the scheduled task.
To access the Simple Scheduled Tasks API the AutomationServices license feature must be enabled and the API user must have the maintainSchedule feature permission specified as part of their role. |
For help with simple scheduled tasks see the related tutorials.
Create a simple scheduled task
A POST
request creates a simple scheduled task.
Request Parameters
Parameter | Description |
---|---|
|
The container locator of the requested scheduled tasks. |
|
The authentication token. |
Request Fields
Path | Type | Description |
---|---|---|
|
|
The identity of the scheduled task. It must be unique and will be allocated if not specified at creation. |
|
|
The name of the scheduled task. This must be unique in the container. |
|
|
The description of the scheduled task. |
|
|
true if schedule is enabled, defaults to true. |
|
|
The Run Property Set for the Scheduled Task |
|
|
A list of run properties. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
Trigger Properties e.g. 'cronExpression'. |
|
|
Quartz Cron Expression. |
|
|
The date and time when the schedule starts in ISO-8601 format. |
|
|
The date and time when the schedule ends in ISO-8601 format. |
|
|
List of follow up actions taken on completion of Data Flow execution. |
|
|
Specifies whether the follow up action is enabled or not. |
|
|
Condition on which to execute the follow up action. SUCCEEDED - execute if previous data flow succeeded, FAILED - execute if previous data flow failed. |
|
|
Action to take. |
|
|
Type of action: executeDataFlowFollowUpAction - execute a data flow, sendEmailFollowUpAction - send an email to a specified list of recipients. |
|
|
Information specific to the action. |
|
|
Locator of data flow to execute when executeDataFlowFollowUpAction is specified. |
|
|
Optional Run Property Set to use with follow up data flow when executeDataFlowFollowUpAction is specified. |
|
|
List of email recipients when sendEmailFollowUpAction is specified. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
Object resource locator. Used to identify the resource. |
|
|
Status of the response. One of: |
Example request
In this example the follow-ups are configured to execute another data flow if the scheduled data flow succeeds and to send an email if either data flow fails to execute.
POST /api/v4/simple-scheduled-tasks?container=object:!tenant:defaultTenant~directory:workspace-id<k=AUTHENTICATION_TOKEN HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
Content-Length: 1230
Host: localhost:8080
{"id":"simple-scheduled-task-v4-id","name":"Schedule Name","description":"Schedule Description","enabled":false,"triggerProperties":{"cronExpression":"0 00 00 1 1/1 ? *","startDateTime":"Start Date is ISO 8601 format","endDateTime":"Start Date is ISO 8601 format"},"dataflowId":"dataflowId","dataflowLocator":null,"runPropertySet":{"id":null,"name":null,"runProperties":[{"name":"runPropertyName1","value":"runPropertyValue1","source":null,"dataType":null,"editorData":null,"managementData":null},{"name":"runPropertyName2","value":"runPropertyValue2","source":null,"dataType":null,"editorData":null,"managementData":null}],"parentRunPropertySetLocators":null,"lastKnownParentNames":null,"description":null},"searchPath":["object:!tenant:defaultTenant~directory:workspace-id"],"runAsUserLocator":"object:!tenant:defaultTenant~user:runAsUser","followUps":[{"condition":"SUCCEEDED","action":{"type":"executeDataFlowFollowUpAction","data":{"runPropertySet":null,"dataflowLocator":"object:!tenant:defaultTenant~directory:workspace-id~graph:followUpGraphId"}},"enabled":true},{"condition":"FAILED","action":{"type":"sendEmailFollowUpAction","data":{"emailDistributionList":["user1@company.com","user2@company.com"]}},"enabled":false}]}
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 152
{
"status" : "OK",
"data" : {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:simple-scheduled-task-v4-id"
}
}
Update a simple scheduled task
A PUT
request updates a simple scheduled task.
Path Parameters
Parameter | Description |
---|---|
|
The locator for the scheduled task to update. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
Request Fields
Path | Type | Description |
---|---|---|
|
|
The identity of the scheduled task. It must be unique and will be allocated if not specified at creation. |
|
|
The name of the scheduled task. This must be unique in the container. |
|
|
The description of the scheduled task. |
|
|
true if schedule is enabled, defaults to true. |
|
|
The Run Property Set for the Scheduled Task |
|
|
A list of run properties. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
Trigger Properties e.g. 'cronExpression'. |
|
|
Quartz Cron Expression. |
|
|
The date and time when the schedule starts in ISO-8601 format. |
|
|
The date and time when the schedule ends in ISO-8601 format. |
|
|
List of follow up actions taken on completion of Data Flow execution. |
|
|
Specifies whether the follow up action is enabled or not. |
|
|
Condition on which to execute the follow up action. SUCCEEDED - execute if previous data flow succeeded, FAILED - execute if previous data flow failed. |
|
|
Action to take. |
|
|
Type of action: executeDataFlowFollowUpAction - execute a data flow, sendEmailFollowUpAction - send an email to a specified list of recipients. |
|
|
Information specific to the action. |
|
|
Locator of data flow to execute when executeDataFlowFollowUpAction is specified. |
|
|
Optional Run Property Set to use with follow up data flow when executeDataFlowFollowUpAction is specified. |
|
|
List of email recipients when sendEmailFollowUpAction is specified. |
Response Fields
None
Example request
PUT /api/v4/simple-scheduled-tasks/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:simple-scheduled-task-v4-id?ltk=AUTHENTICATION_TOKEN HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
Content-Length: 1230
Host: localhost:8080
{"id":"simple-scheduled-task-v4-id","name":"Schedule Name","description":"Schedule Description","enabled":false,"triggerProperties":{"cronExpression":"0 00 00 1 1/1 ? *","startDateTime":"Start Date is ISO 8601 format","endDateTime":"Start Date is ISO 8601 format"},"dataflowId":"dataflowId","dataflowLocator":null,"runPropertySet":{"id":null,"name":null,"runProperties":[{"name":"runPropertyName1","value":"runPropertyValue1","source":null,"dataType":null,"editorData":null,"managementData":null},{"name":"runPropertyName2","value":"runPropertyValue2","source":null,"dataType":null,"editorData":null,"managementData":null}],"parentRunPropertySetLocators":null,"lastKnownParentNames":null,"description":null},"searchPath":["object:!tenant:defaultTenant~directory:workspace-id"],"runAsUserLocator":"object:!tenant:defaultTenant~user:runAsUser","followUps":[{"condition":"SUCCEEDED","action":{"type":"executeDataFlowFollowUpAction","data":{"runPropertySet":null,"dataflowLocator":"object:!tenant:defaultTenant~directory:workspace-id~graph:followUpGraphId"}},"enabled":true},{"condition":"FAILED","action":{"type":"sendEmailFollowUpAction","data":{"emailDistributionList":["user1@company.com","user2@company.com"]}},"enabled":false}]}
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 162
{
"status" : "OK",
"data" : {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:simple-scheduled-task-v4-id"
}
}
Get a specified scheduled task
A GET
request returns the specified scheduled task.
Path Parameters
Parameter | Description |
---|---|
|
The object resource locator of the requested scheduled task. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
|
Specifies the fields to return in the response. One or more of |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested scheduled task. |
|
|
Status of the response. One of: |
|
|
The identity of the scheduled task. It must be unique and will be allocated if not specified at creation. |
|
|
The name of the scheduled task. This must be unique in the container. |
|
|
The description of the scheduled task. |
|
|
true if schedule is enabled, defaults to true. |
|
|
The Run Property Set for the Scheduled Task |
|
|
A list of run properties. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
Trigger Properties e.g. 'cronExpression'. |
|
|
Quartz Cron Expression. |
|
|
The date and time when the schedule starts in ISO-8601 format. |
|
|
The date and time when the schedule ends in ISO-8601 format. |
|
|
List of follow up actions taken on completion of Data Flow execution. |
|
|
Specifies whether the follow up action is enabled or not. |
|
|
Condition on which to execute the follow up action. SUCCEEDED - execute if previous data flow succeeded, FAILED - execute if previous data flow failed. |
|
|
Action to take. |
|
|
Type of action: executeDataFlowFollowUpAction - execute a data flow, sendEmailFollowUpAction - send an email to a specified list of recipients. |
|
|
Information specific to the action. |
|
|
Locator of data flow to execute when executeDataFlowFollowUpAction is specified. |
|
|
Optional Run Property Set to use with follow up data flow when executeDataFlowFollowUpAction is specified. |
|
|
List of email recipients when sendEmailFollowUpAction is specified. |
|
|
Metadata for the resource. |
|
|
The resource locator that uniquely identifies the resource. |
|
|
The userid of the user that created the resource. |
|
|
The username of the user that created the resource. |
|
|
Creation time of resource in ISO-8601 format. |
|
|
The userid of the user that last modified the resource. |
|
|
The username of the user that last modified the resource. |
|
|
Last modification time of resource in ISO-8601 format. |
|
|
The resource locator that uniquely identifies the container resource. |
|
|
The resource type. |
|
|
The resource id. |
|
|
True if the resource id is universally addressable. |
Example request
GET /api/v4/simple-scheduled-tasks/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:simple-scheduled-task-v4-id?ltk=AUTHENTICATION_TOKEN&fields=object,metadata HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3002
{
"status" : "OK",
"data" : {
"metadata" : {
"createdByName" : "Created By User Name",
"modifiedByName" : "Modified By User Name",
"browsingMetadata" : {
"name" : "Scheduled Task",
"description" : "Scheduled Task"
},
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:scheduled-task-id-001",
"containerLocator" : "object:!tenant:defaultTenant~directory:workspace-id",
"createdBy" : "created-by-user-Id",
"createdOn" : "2023-05-31T03:10:08+0000",
"modifiedBy" : "modified-by-user-Id",
"modifiedOn" : "2023-05-31T03:10:08+0000",
"resourceId" : {
"objectType" : "simple-scheduled-task-v4",
"objectId" : "scheduled-task-id-001",
"universal" : false
},
"universalLocator" : null,
"universalContainerLocator" : null
},
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:scheduled-task-id-001",
"object" : {
"id" : "scheduled-task-id-001",
"name" : "Scheduled Task",
"description" : "Schedule Description",
"enabled" : false,
"triggerProperties" : {
"cronExpression" : "0 00 00 1 1/1 ? *",
"startDateTime" : "Start Date is ISO 8601 format",
"endDateTime" : "Start Date is ISO 8601 format"
},
"dataflowId" : "dataflowId",
"dataflowLocator" : "object:!tenant:defaultTenant~directory:workspace-id~graph:dataflowId",
"runPropertySet" : {
"id" : null,
"name" : "Scheduled Task",
"description" : null,
"runProperties" : [ {
"name" : "runPropertyName1",
"value" : "runPropertyValue1",
"source" : null,
"dataType" : null,
"encryptionType" : "NO_ENCRYPTION",
"editorData" : null,
"managementData" : null
}, {
"name" : "runPropertyName2",
"value" : "runPropertyValue2",
"source" : null,
"dataType" : null,
"encryptionType" : "NO_ENCRYPTION",
"editorData" : null,
"managementData" : null
} ],
"lastKnownParentNames" : null,
"parentRunPropertySetLocators" : [ ]
},
"searchPath" : [ "object:!tenant:defaultTenant~directory:workspace-id" ],
"runAsUserLocator" : null,
"followUps" : [ {
"condition" : "SUCCEEDED",
"action" : {
"type" : "executeDataFlowFollowUpAction",
"data" : {
"dataflowLocator" : "object:!tenant:defaultTenant~directory:workspace-idgraph%3AfollowUpDataFlowId",
"runPropertySet" : null
}
},
"enabled" : true
}, {
"condition" : "FAILED",
"action" : {
"type" : "sendEmailFollowUpAction",
"data" : {
"emailDistributionList" : [ "user1@company.com", "user2@company.com" ]
}
},
"enabled" : true
} ]
}
}
}
Get a list of scheduled tasks
A GET
request returns a list of scheduled tasks.
Path Parameters
None
Request Parameters
Parameter | Description |
---|---|
|
The container locator of the requested scheduled tasks. |
|
Specifies the fields to return in the response. One or more of |
|
An optional FIQL filter expression. Supports searching by the 'name' attribute. For example |
|
The authentication token. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested scheduled task. |
|
|
Status of the response. One of: |
|
|
The identity of the scheduled task. It must be unique and will be allocated if not specified at creation. |
|
|
The name of the scheduled task. This must be unique in the container. |
|
|
The description of the scheduled task. |
|
|
true if schedule is enabled, defaults to true. |
|
|
The Run Property Set for the Scheduled Task |
|
|
A list of run properties. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
Trigger Properties e.g. 'cronExpression'. |
|
|
Quartz Cron Expression. |
|
|
The date and time when the schedule starts in ISO-8601 format. |
|
|
The date and time when the schedule ends in ISO-8601 format. |
|
|
List of follow up actions taken on completion of Data Flow execution. |
|
|
Specifies whether the follow up action is enabled or not. |
|
|
Condition on which to execute the follow up action. SUCCEEDED - execute if previous data flow succeeded, FAILED - execute if previous data flow failed. |
|
|
Action to take. |
|
|
Type of action: executeDataFlowFollowUpAction - execute a data flow, sendEmailFollowUpAction - send an email to a specified list of recipients. |
|
|
Information specific to the action. |
|
|
Locator of data flow to execute when executeDataFlowFollowUpAction is specified. |
|
|
Optional Run Property Set to use with follow up data flow when executeDataFlowFollowUpAction is specified. |
|
|
List of email recipients when sendEmailFollowUpAction is specified. |
Example request
GET /api/v4/simple-scheduled-tasks?container=object:!tenant:defaultTenant~directory:workspace-id&fields=object&filter=name%3D%3D'Schedule%20Name'<k=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 4560
{
"status" : "OK",
"data" : {
"objects" : [ {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:scheduled-task-id-001",
"object" : {
"id" : "scheduled-task-id-001",
"name" : "First Scheduled Task",
"description" : "Schedule Description",
"enabled" : false,
"triggerProperties" : {
"cronExpression" : "0 00 00 1 1/1 ? *",
"startDateTime" : "Start Date is ISO 8601 format",
"endDateTime" : "Start Date is ISO 8601 format"
},
"dataflowId" : "dataflowId",
"dataflowLocator" : "object:!tenant:defaultTenant~directory:workspace-id~graph:dataflowId",
"runPropertySet" : {
"id" : null,
"name" : "First Scheduled Task",
"description" : null,
"runProperties" : [ {
"name" : "runPropertyName1",
"value" : "runPropertyValue1",
"source" : null,
"dataType" : null,
"encryptionType" : "NO_ENCRYPTION",
"editorData" : null,
"managementData" : null
}, {
"name" : "runPropertyName2",
"value" : "runPropertyValue2",
"source" : null,
"dataType" : null,
"encryptionType" : "NO_ENCRYPTION",
"editorData" : null,
"managementData" : null
} ],
"lastKnownParentNames" : null,
"parentRunPropertySetLocators" : [ ]
},
"searchPath" : [ "object:!tenant:defaultTenant~directory:workspace-id" ],
"runAsUserLocator" : null,
"followUps" : [ {
"condition" : "SUCCEEDED",
"action" : {
"type" : "executeDataFlowFollowUpAction",
"data" : {
"dataflowLocator" : "object:!tenant:defaultTenant~directory:workspace-idgraph%3AfollowUpDataFlowId",
"runPropertySet" : null
}
},
"enabled" : true
}, {
"condition" : "FAILED",
"action" : {
"type" : "sendEmailFollowUpAction",
"data" : {
"emailDistributionList" : [ "user1@company.com", "user2@company.com" ]
}
},
"enabled" : true
} ]
}
}, {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:scheduled-task-id-002",
"object" : {
"id" : "scheduled-task-id-002",
"name" : "Second Scheduled Task",
"description" : "Schedule Description",
"enabled" : false,
"triggerProperties" : {
"cronExpression" : "0 00 00 1 1/1 ? *",
"startDateTime" : "Start Date is ISO 8601 format",
"endDateTime" : "Start Date is ISO 8601 format"
},
"dataflowId" : "dataflowId",
"dataflowLocator" : "object:!tenant:defaultTenant~directory:workspace-id~graph:dataflowId",
"runPropertySet" : {
"id" : null,
"name" : "Second Scheduled Task",
"description" : null,
"runProperties" : [ {
"name" : "runPropertyName1",
"value" : "runPropertyValue1",
"source" : null,
"dataType" : null,
"encryptionType" : "NO_ENCRYPTION",
"editorData" : null,
"managementData" : null
}, {
"name" : "runPropertyName2",
"value" : "runPropertyValue2",
"source" : null,
"dataType" : null,
"encryptionType" : "NO_ENCRYPTION",
"editorData" : null,
"managementData" : null
} ],
"lastKnownParentNames" : null,
"parentRunPropertySetLocators" : [ ]
},
"searchPath" : [ "object:!tenant:defaultTenant~directory:workspace-id" ],
"runAsUserLocator" : null,
"followUps" : [ {
"condition" : "SUCCEEDED",
"action" : {
"type" : "executeDataFlowFollowUpAction",
"data" : {
"dataflowLocator" : "object:!tenant:defaultTenant~directory:workspace-idgraph%3AfollowUpDataFlowId",
"runPropertySet" : null
}
},
"enabled" : true
}, {
"condition" : "FAILED",
"action" : {
"type" : "sendEmailFollowUpAction",
"data" : {
"emailDistributionList" : [ "user1@company.com", "user2@company.com" ]
}
},
"enabled" : true
} ]
}
} ]
}
}
Delete a simple scheduled task
A DELETE
request deletes a simple scheduled task.
Path Parameters
Parameter | Description |
---|---|
|
The locator of the scheduled task to delete. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
Request Fields
None
Response Fields
None
Example request
DELETE /api/v4/simple-scheduled-tasks/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:simple-scheduled-task-v4-id?ltk=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 162
{
"status" : "OK",
"data" : {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:simple-scheduled-task-v4-id"
}
}
Ad-hoc run of a simple scheduled task
A POST
request executes an ad-hoc run of a simple scheduled task.
Run property values can be overridden for this run only if required.
A failed execution plan state can be run again by specifying the execution plan state locator.
Path Parameters
Parameter | Description |
---|---|
|
The locator of the scheduled task to run. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
Request Fields
Path | Type | Description |
---|---|---|
|
|
The locator for the execution plan state locator when re-running a failed execution plan state. |
|
|
The Run Property Set for the Scheduled Task |
|
|
A list of run properties. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
The concurrent execution strategy. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
Object resource locator of execution plan state for run. Use with the Execution Plan States API to identify the state of the run. |
|
|
Status of the response. One of: |
Example request
POST /api/v4/simple-scheduled-tasks/run-now/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:simple-scheduled-task-v4-id?ltk=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded
ltk=AUTHENTICATION_TOKEN
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 197
{
"status" : "OK",
"data" : {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:simple-scheduled-task-v4-id~execution-plan-state:execution-plan-state-id"
}
}
Example request to re-run failed task
POST /api/v4/simple-scheduled-tasks/run-now/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:simple-scheduled-task-v4-id?ltk=AUTHENTICATION_TOKEN HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
Content-Length: 338
Host: localhost:8080
{"executionPlanStateLocator":"object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:simple-scheduled-task-v4-idexecution-plan-state:execution-plan-state-id","overriddenRunPropertySet":null,"overriddenSuccessDataflowRunPropertySet":null,"overriddenFailDataflowRunPropertySet":null,"concurrentExecutionStrategy":null}
Example request to run with overridden run property values
POST /api/v4/simple-scheduled-tasks/run-now/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task-v4:simple-scheduled-task-v4-id?ltk=AUTHENTICATION_TOKEN HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
Content-Length: 584
Host: localhost:8080
{"executionPlanStateLocator":null,"overriddenRunPropertySet":{"id":null,"name":null,"runProperties":[{"name":"runPropertyName1","value":"overriddenrunPropertyValue1","source":null,"dataType":null,"editorData":null,"managementData":null},{"name":"runPropertyName2","value":"overriddenrunPropertyValue2","source":null,"dataType":null,"editorData":null,"managementData":null}],"parentRunPropertySetLocators":null,"lastKnownParentNames":null,"description":null},"overriddenSuccessDataflowRunPropertySet":null,"overriddenFailDataflowRunPropertySet":null,"concurrentExecutionStrategy":null}
Errors
See errors for details of the error response.
Error Code | Description | Arguments |
---|---|---|
lae.scheduler.invalidCronExpression |
The specified |
|
lae.scheduler.missingCronExpression |
The |
|
lae.scheduler.scheduledTaskNameNotUnique |
The specified |
|
lae.scheduler.scheduledTaskNameNotSpecified |
The |
|
lae.scheduler.scheduledTaskIdNotSpecified |
The |
|
lae.scheduler.executionPlanStateRunning |
The scheduled task could not be deleted as it is currently running. |
|
Scheduler Management
It is possible to suspend and resume the scheduler. No new runs will be started while the scheduler is suspended. Ongoing runs will complete.
When the scheduler is resumed, the next run for each scheduled task will be started at its allotted time. Runs that were scheduled to start while the scheduler was suspended will be discarded.
All scheduled tasks are affected by the suspension and resumption of the scheduler including:
-
Scheduled data flow executions
-
Scheduled deletion of temporary data
-
Scheduled backups
-
Scheduled user profile imports
Get Scheduler Status
A GET
request is used to retrieve the status of the scheduler. The status can be:
-
RUNNING
-
SUSPENDED
Request parameters
None
Request fields
None
Response fields
Path | Type | Description |
---|---|---|
|
|
Scheduler Status. Can be RUNNING or SUSPENDED |
|
|
HTTP Status Code. |
Example request
GET /api/v3/scheduler/status HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 43
{"status":"OK","data":{"status":"RUNNING"}}
Suspend Scheduler
A POST
request is used to suspend the scheduler. The status will be SUSPENDED
after the request.
Request parameters
None
Request fields
None
Response fields
Path | Type | Description |
---|---|---|
|
|
Scheduler Status. Will be SUSPENDED if request is successful. |
|
|
HTTP Status Code. |
Example request
POST /api/v3/scheduler/suspend HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 45
{"status":"OK","data":{"status":"SUSPENDED"}}
Resume Scheduler
A POST
request is used to suspend the scheduler. The status will be RUNNING
after the request.
Request parameters
None
Request fields
None
Response fields
Path | Type | Description |
---|---|---|
|
|
Scheduler Status. Will be RUNNING if request is successful. |
|
|
HTTP Status Code. |
Example request
POST /api/v3/scheduler/resume HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 43
{"status":"OK","data":{"status":"RUNNING"}}
Execution Plan States
Execution Plan States store the status of scheduled runs.
Get a specified execution plan state
GET
request returns the specified execution plan state.
Path Parameters
Parameter | Description |
---|---|
|
The object resource locator of the requested execution plan state. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
|
Specifies the fields to return in the response. One or more of |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested execution plan state. |
|
|
Status of the response. One of: |
|
|
The identity of the execution plan state. |
|
|
The name of the execution plan state. |
|
|
The status of the execution plan state. Can be one of |
|
|
The Object Resource Locator of the Execution Plan. For future use. |
|
|
The plan state. The result for segments in the execution plan state. |
|
|
Status of the segment. |
|
|
Start time of the segment. |
|
|
Duration of the segment. |
|
|
Data Flow executed in the segment. |
|
|
The start time of the first execution of this execution plan state in ISO-8601 format. |
|
|
The end time of the last execution of this execution plan state in ISO-8601 format. |
|
|
The total duration in seconds of all executions of this execution plan state. |
|
|
Error details in the case of an unsuccessful execution. |
|
|
Metadata for the resource. |
|
|
The resource locator that uniquely identifies the resource. |
|
|
The userid of the user that created the resource. |
|
|
The username of the user that created the resource. |
|
|
Creation time of resource in ISO-8601 format. |
|
|
The userid of the user that last modified the resource. |
|
|
The username of the user that last modified the resource. |
|
|
Last modification time of resource in ISO-8601 format. |
|
|
The resource locator that uniquely identifies the container resource. |
|
|
The resource type. |
|
|
The resource id. |
|
|
True if the resource id is universally addressable. |
Example request
GET /api/v3/execution-plan-states/object:!tenant:defaultTenant~directory:workspace-id~executionplanstate:executionplanstate-id?ltk=AUTHENTICATION_TOKEN&fields=object,metadata HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1841
{
"status" : "OK",
"data" : {
"metadata" : {
"createdByName" : "Created By User Name",
"modifiedByName" : "Modified By User Name",
"browsingMetadata" : {
"name" : "Execution Plan State",
"description" : "Execution Plan State"
},
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~executionplanstate:execution-plan-state-id-001",
"containerLocator" : "object:!tenant:defaultTenant~directory:workspace-id",
"createdBy" : "created-by-user-Id",
"createdOn" : "2023-05-31T03:10:07+0000",
"modifiedBy" : "modified-by-user-Id",
"modifiedOn" : "2023-05-31T03:10:07+0000",
"resourceId" : {
"objectType" : "executionplanstate",
"objectId" : "execution-plan-state-id-001",
"universal" : false
},
"universalLocator" : null,
"universalContainerLocator" : null
},
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~executionplanstate:executionplanstate-id",
"object" : {
"id" : "execution-plan-state-id-001",
"name" : null,
"status" : "COMPLETED",
"startTime" : "2023-05-31T03:08:07+0000",
"endTime" : "2023-05-31T03:10:07+0000",
"durationInSeconds" : 120,
"executionPlanLocator" : "object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:scheduled-task-id~execution-plan:execution-plan-id",
"planState" : [ {
"executionPlanNodeId" : "776d4568-4f24-4176-a751-45154e19133a",
"executionSession" : "object:execution-session:execution-session-id",
"overriddenRunProperties" : null,
"status" : null,
"startTime" : "2023-05-31T03:08:07+0000",
"duration" : 120000,
"dataFlowLocator" : "object:!tenant:defaultTenant~directory:workspace-id~graph:graph-id"
} ]
}
}
}
Get a list of execution plan states
GET
request returns the list of execution plan states.
Path Parameters
None
Request Parameters
Parameter | Description |
---|---|
|
The container locator of the requested execution plan states. |
|
Specifies the fields to return in the response. One or more of |
|
An optional FIQL filter expression. Supports searching by the 'name' attribute. For example |
|
The authentication token. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested execution plan state. |
|
|
Status of the response. One of: |
|
|
The identity of the execution plan state. |
|
|
The name of the execution plan state. |
|
|
The status of the execution plan state. Can be one of |
|
|
The Object Resource Locator of the Execution Plan. For future use. |
|
|
The plan state. The result for segments in the execution plan state. |
|
|
Status of the segment. |
|
|
Start time of the segment. |
|
|
Duration of the segment. |
|
|
Data Flow executed in the segment. |
|
|
The start time of the first execution of this execution plan state in ISO-8601 format. |
|
|
The end time of the last execution of this execution plan state in ISO-8601 format. |
|
|
The total duration in seconds of all executions of this execution plan state. |
|
|
Error details in the case of an unsuccessful execution. |
Example request
GET /api/v3/execution-plan-states?container=object:!tenant:defaultTenant~directory:workspace-id&fields=object&filter=status%3D%3D'COMPLETED'<k=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2036
{
"status" : "OK",
"data" : {
"objects" : [ {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~executionplanstate:execution-plan-state-id-001",
"object" : {
"id" : "execution-plan-state-id-001",
"name" : null,
"status" : "COMPLETED",
"startTime" : "2023-05-31T03:08:07+0000",
"endTime" : "2023-05-31T03:10:07+0000",
"durationInSeconds" : 120,
"executionPlanLocator" : "object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:scheduled-task-id~execution-plan:execution-plan-id",
"planState" : [ {
"executionPlanNodeId" : "67f148f8-278c-401e-861e-bbe0f0aa2bd9",
"executionSession" : "object:execution-session:execution-session-id",
"overriddenRunProperties" : null,
"status" : null,
"startTime" : "2023-05-31T03:08:07+0000",
"duration" : 120000,
"dataFlowLocator" : "object:!tenant:defaultTenant~directory:workspace-id~graph:graph-id"
} ]
}
}, {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~executionplanstate:execution-plan-state-id-002",
"object" : {
"id" : "execution-plan-state-id-002",
"name" : null,
"status" : "COMPLETED",
"startTime" : "2023-05-31T03:08:07+0000",
"endTime" : "2023-05-31T03:10:07+0000",
"durationInSeconds" : 120,
"executionPlanLocator" : "object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:scheduled-task-id~execution-plan:execution-plan-id",
"planState" : [ {
"executionPlanNodeId" : "3e09d689-ac16-4155-9dbe-3f072c4972c7",
"executionSession" : "object:execution-session:execution-session-id",
"overriddenRunProperties" : null,
"status" : null,
"startTime" : "2023-05-31T03:08:07+0000",
"duration" : 120000,
"dataFlowLocator" : "object:!tenant:defaultTenant~directory:workspace-id~graph:graph-id"
} ]
}
} ]
}
}
Delete an execution plan state
A DELETE
request deletes an execution plan state.
Path Parameters
Parameter | Description |
---|---|
|
The locator of the execution plan state to delete. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
Request Fields
None
Response Fields
None
Example request
DELETE /api/v3/execution-plan-states/object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:scheduled-task-id~execution-plan-state:execution-plan-state-id?ltk=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 187
{
"status" : "OK",
"data" : {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:scheduled-task-id~execution-plan-state:execution-plan-state-id"
}
}
LNA Import
LNA import Service is a RESTful service for importing LNAs.
Import an LNA
POST
request imports an LNA.
Path Parameters
None
Request Parameters
Parameter | Description |
---|---|
|
Target workspace or directory locator. |
|
Filename of LNA to import. |
|
If set to true, existing items at the target location with the same name or id will be overwritten. |
|
If set to true, items will be imported even if they have missing dependencies. |
|
The authentication token. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
Total error count for imported items. |
|
|
A map containing imported items and the status of the import for each item. |
|
|
Import item status id. In these examples the id is |
|
|
The object resource locator for the imported item. This is where the item is located in the system. |
|
|
The name of the conflicting item when the import of this item has failed due to an id or name conflict. |
|
|
The name of this item when the import of this item has failed due to an id conflict. |
|
|
The import item status. Can be one of |
|
|
The total number of resoultion and compilation errors in the imported items. |
|
|
Status of the response. One of: |
Example request
POST /api/v3/lna/import?destinationLocator=object:!tenant:defaultTenant~directory:workspace-id&file=Dataflow.lna&shouldOverwrite=true&ignoreErrors=false<k=AUTHENTICATION_TOKEN HTTP/1.1
Content-Type: multipart/form-data;charset=ISO-8859-1; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Host: localhost:8080
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=destinationLocator
object:!tenant:defaultTenant~directory:workspace-id
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file
Dataflow.lna
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=shouldOverwrite
true
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=ignoreErrors
false
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=ltk
AUTHENTICATION_TOKEN
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file; filename=file
Content-Type: text/plain
fileContent
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 454
{
"status" : "OK",
"data" : {
"totalErrorCount" : 0,
"importedItems" : {
"object:!edit-session:id~graph:id" : {
"id" : "object:!edit-session:id~graph:id",
"destinationLocator" : "object:!tenant:defaultTenant~directory:workspace-id~graph:id",
"status" : "SUCCESS",
"saveItemName" : "Data Flow",
"conflictingItemName" : "Data Flow",
"resolutionCompilationErrorCount" : 0
}
}
}
}
Tutorials
Authentication and Login Flows
There are a number of steps to the authentication process:
-
Get the login flow entry point URI for the client type. REST API clients use the
rest
login flow. -
Use the
rest
login flowentryPointUri
to get the tenant methods that can be used to identify the tenant that the user belongs to. -
Use the
methods
returned by Tenant Methods to identify the tenant that the user belongs to. Currently only Automatic Tenant Resolution is supported. Note that because single-tenant deployments always identify the tenant using the tenant locatorobject:!tenant:defaultTenant
, a client that only uses a single-tenant deployment may skip this step and the previous steps, and use the default tenant locator instead. -
Using the tenant locator, get the authentication methods to identify the authentication methods supported by the tenant. Data360 Analyze currently supports o authentication methods - Username-Password and SAML2. These methods may be made available via configuration and licensing. If the system is not configured to support SAML2 then this step may be skipped and the Username-Password authentication APIs used directly. (Note that it is not possible to authenticate via the API using SAML2).
-
Use the returned authentication methods to initiate, renew, and unlock the user session. Each authentication method has its own set of APIs for user session management. See the User Session section.
-
On completion of activity logout of the session using the appropriate logout API for the authentication method.
Directories and Workspaces
Directories
The directories API can be used to identify and navigate to artifacts in the system. The table lists some useful system-generated directories.
Directory Name | Description | Object Resource Locator |
---|---|---|
ROOT |
The root directory containing all artifacts for the tenant. |
|
USERS |
Directory containing all the users' personal directories (My Documents). |
|
Public Documents |
Directory containing shared artifacts. |
|
Data360 Nodes |
Directory containing system-defined nodes. |
|
A user’s My Documents directory has the same name as the user. To locate a user’s My Documents directory using the directories API, specify the USERS directory as container
and the user name in a filter
e.g. GET localhost:8080/api/v3/directories?ltk=<AUTHENTICATION_TOKEN>&container=object:!tenant:defaultTenant~directory:__Root__~directory:__Users__&filter=name==username
Workspaces
A workspace is a symbolic link to a directory. Public Documents can be referenced as a workspace with the ORL object:!tenant:defaultTenant~workspace:lavastormShared
.
Each user’s My Documents folder can also be referenced as a workspace. Identify the workspace of a specific user as follows:
-
Retrieve the user locator for the user using the users API. Filter by
name
and setfields=object,metadata
. Thelocator
is returned as part of the metadata. -
Retrieve the workspace locator for the specified user using the user preferences API. Use the user locator as the path parameter.
Simple Scheduled Tasks
This tutorial guides you through a typical scheduled task workflow, showing you the steps required to schedule a data flow, retrieve the schedule run status and run a data flow.
Scheduling a data flow
-
Obtain an authentication token. See User Session. You will need to use this authentication token in all subsequent requests.
-
A scheduled task must be contained in a workspace or a directory. To locate a directory use the directories API. To locate a workspace use the workspaces API. The workspace is a symbolic link to a directory. Public Documents can be referenced as a workspace. Each user’s My Documents folder can also be referenced as a workspace. Identify the workspace of a specific user as follows:
-
Retrieve the user locator for the user using the users API. Filter by
name
and setfields=object,metadata
. Thelocator
is returned as part of the metadata. -
Retrieve the workspace locator for the specified user using the user preferences API. Use the user locator as the path parameter.
-
-
Retrieve the locator for the data flow you wish to schedule using the data flows API. Filter by
name
and setfields=object,metadata
. -
Create a scheduled task using the simple scheduled tasks API. Use the workspace or directory locator as
container
. In the body of the request specify the data flow locator. Set run property values in the run property set using the run property names from the data flow.
If your request is successful, you will receive a scheduled task locator, which you can use to reference the schedule in subsequent requests.
Now that you have created a schedule, and assuming you set it to 'enabled', then your data flow will start running on the frequency specified in the schedule.
Retrieving schedule run status
When a data flow has run, either via the automated schedule or by running a schedule in an ad-hoc fashion, you can retrieve the run results as follows:
-
Obtain an authentication token. See User Session.
-
Use the execution plan states API with scheduled task locator as
container
ID to retrieve an ordered list of runs generated by the schedule, ordered by most recent. The list includes the pass/fail results for the data flow.
To investigate a run, login to the Data360 Analyze application UI, where the schedules will be listed. For each run produced by the schedule, you can open the run in a read-only viewer, enabling you to see the data and any errors that may have occurred.
Running a data flow
The Simple Scheduled Task API set can be used to perform an ad-hoc run of a data flow, with the added benefit that once a schedule is set up for a data flow then each run status can be easily retrieved.
-
Follow the steps in scheduling a data flow to setup a schedule for the required data flow. When you create the schedule, ensure that you set it to be disabled.
-
Use the ad-hoc run API with the scheduled task locator as the path parameter to run the schedule immediately. The run result will appear in the list of scheduled runs for the schedule. See retrieving schedule run status.
Re-running a failed scheduled run
The Simple Scheduled Task API set can be used to re-run a failed run.
-
Follow the steps in retrieve schedule run status with the
fields=object,metadata
field specified to identify theexecutionPlanStateLocator
of the failed run. -
Use the ad-hoc run API with the scheduled task locator as the path parameter and the
executionPlanStateLocator
specified in the body of the request to re-run the schedule immediately. The updated run result will appear in the list of scheduled runs for the schedule. See retrieving schedule run status.
Deprecated APIs
Simple Scheduled Task Version 3
Create a simple scheduled task
This API is deprecated and is superseded by version v4.
A POST
request creates a simple scheduled task.
Request Parameters
Parameter | Description |
---|---|
|
The container locator of the requested scheduled tasks. |
|
The authentication token. |
Request Fields
Path | Type | Description |
---|---|---|
|
|
The identity of the scheduled task. It must be unique and will be allocated if not specified at creation. |
|
|
The name of the scheduled task. This must be unique in the container. |
|
|
The description of the scheduled task. |
|
|
true if schedule is enabled, defaults to true. |
|
|
The identity of the data flow to schedule. See dataflows. |
|
|
The search path is a list of workspaces to search when locating the data flow. See dataflows. |
|
|
A map of run properties. |
|
|
The name of the run property is used as the key to the run property details in the map. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
The name of the run property is used as the key to the run property details in the map. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
Trigger Properties e.g. 'cronExpression'. |
|
|
Quartz Cron Expression. |
|
|
The date and time when the schedule starts in ISO-8601 format. |
|
|
The date and time when the schedule ends in ISO-8601 format. |
|
|
The username that will run the schedule. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
Object resource locator. Used to identify the resource. |
|
|
Status of the response. One of: |
Example request
POST /api/v3/simple-scheduled-tasks?container=object:!tenant:defaultTenant~directory:workspace-id<k=AUTHENTICATION_TOKEN HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
Content-Length: 689
Host: localhost:8080
{"id":"simple-scheduled-task-id","name":"Schedule Name","description":"Schedule Description","enabled":false,"triggerProperties":{"cronExpression":"0 00 00 1 1/1 ? *","startDateTime":"Start Date is ISO 8601 format","endDateTime":"Start Date is ISO 8601 format"},"runAs":"runAsUsername","dataflowId":"dataflowId","runProperties":{"runPropertyName2":{"name":"runPropertyName2","value":"runPropertyValue2","source":null,"dataType":null,"editorData":null,"managementData":null},"runPropertyName1":{"name":"runPropertyName1","value":"runPropertyValue1","source":null,"dataType":null,"editorData":null,"managementData":null}},"searchPath":["object:!tenant:defaultTenant~directory:workspace-id"]}
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 161
{
"status" : "OK",
"data" : {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:20bdb287-b7b2-47ab-92d5-7a7c05865a42"
}
}
Update a simple scheduled task
This API is deprecated and is superseded by version v4.
A PUT
request updates a simple scheduled task.
Path Parameters
Parameter | Description |
---|---|
|
The locator for the scheduled task to update. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
Request Fields
Path | Type | Description |
---|---|---|
|
|
The identity of the scheduled task. It must be unique and will be allocated if not specified at creation. |
|
|
The name of the scheduled task. This must be unique in the container. |
|
|
The description of the scheduled task. |
|
|
true if schedule is enabled, defaults to true. |
|
|
The identity of the data flow to schedule. See dataflows. |
|
|
The search path is a list of workspaces to search when locating the data flow. See dataflows. |
|
|
A map of run properties. |
|
|
The name of the run property is used as the key to the run property details in the map. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
The name of the run property is used as the key to the run property details in the map. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
Trigger Properties e.g. 'cronExpression'. |
|
|
Quartz Cron Expression. |
|
|
The date and time when the schedule starts in ISO-8601 format. |
|
|
The date and time when the schedule ends in ISO-8601 format. |
|
|
The username that will run the schedule. |
Response Fields
None
Example request
PUT /api/v3/simple-scheduled-tasks/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:simple-scheduled-task-id?ltk=AUTHENTICATION_TOKEN HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
Content-Length: 689
Host: localhost:8080
{"id":"simple-scheduled-task-id","name":"Schedule Name","description":"Schedule Description","enabled":false,"triggerProperties":{"cronExpression":"0 00 00 1 1/1 ? *","startDateTime":"Start Date is ISO 8601 format","endDateTime":"Start Date is ISO 8601 format"},"runAs":"runAsUsername","dataflowId":"dataflowId","runProperties":{"runPropertyName2":{"name":"runPropertyName2","value":"runPropertyValue2","source":null,"dataType":null,"editorData":null,"managementData":null},"runPropertyName1":{"name":"runPropertyName1","value":"runPropertyValue1","source":null,"dataType":null,"editorData":null,"managementData":null}},"searchPath":["object:!tenant:defaultTenant~directory:workspace-id"]}
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 156
{
"status" : "OK",
"data" : {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:simple-scheduled-task-id"
}
}
Get a specified scheduled task
This API is deprecated and is superseded by version v4.
A GET
request returns the specified scheduled task.
Path Parameters
Parameter | Description |
---|---|
|
The object resource locator of the requested scheduled task. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
|
Specifies the fields to return in the response. One or more of |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested scheduled task. |
|
|
Status of the response. One of: |
|
|
The identity of the scheduled task. It must be unique and will be allocated if not specified at creation. |
|
|
The name of the scheduled task. This must be unique in the container. |
|
|
The description of the scheduled task. |
|
|
true if schedule is enabled, defaults to true. |
|
|
The identity of the data flow to schedule. See dataflows. |
|
|
The search path is a list of workspaces to search when locating the data flow. See dataflows. |
|
|
A map of run properties. |
|
|
The name of the run property is used as the key to the run property details in the map. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
The name of the run property is used as the key to the run property details in the map. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
Trigger Properties e.g. 'cronExpression'. |
|
|
Quartz Cron Expression. |
|
|
The date and time when the schedule starts in ISO-8601 format. |
|
|
The date and time when the schedule ends in ISO-8601 format. |
|
|
The username that will run the schedule. |
|
|
Metadata for the resource. |
|
|
The resource locator that uniquely identifies the resource. |
|
|
The userid of the user that created the resource. |
|
|
The username of the user that created the resource. |
|
|
Creation time of resource in ISO-8601 format. |
|
|
The userid of the user that last modified the resource. |
|
|
The username of the user that last modified the resource. |
|
|
Last modification time of resource in ISO-8601 format. |
|
|
The resource locator that uniquely identifies the container resource. |
|
|
The resource type. |
|
|
The resource id. |
|
|
True if the resource id is universally addressable. |
Example request
GET /api/v3/simple-scheduled-tasks/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:simple-scheduled-task-id?ltk=AUTHENTICATION_TOKEN&fields=object,metadata HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2056
{
"status" : "OK",
"data" : {
"metadata" : {
"createdByName" : "Created By User Name",
"modifiedByName" : "Modified By User Name",
"browsingMetadata" : {
"name" : "Scheduled Task",
"description" : "Scheduled Task"
},
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:scheduled-task-id-001",
"containerLocator" : "object:!tenant:defaultTenant~directory:workspace-id",
"createdBy" : "created-by-user-Id",
"createdOn" : "2023-05-31T03:10:07+0000",
"modifiedBy" : "modified-by-user-Id",
"modifiedOn" : "2023-05-31T03:10:07+0000",
"resourceId" : {
"objectType" : "simple-scheduled-task",
"objectId" : "scheduled-task-id-001",
"universal" : false
},
"universalLocator" : null,
"universalContainerLocator" : null
},
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:simple-scheduled-task-id",
"object" : {
"id" : "scheduled-task-id-001",
"name" : "Scheduled Task",
"description" : "Schedule Description",
"enabled" : false,
"triggerProperties" : {
"cronExpression" : "0 00 00 1 1/1 ? *",
"startDateTime" : "Start Date is ISO 8601 format",
"endDateTime" : "Start Date is ISO 8601 format"
},
"runAs" : "runAsUsername",
"dataflowId" : "dataflowId",
"runProperties" : {
"runPropertyName2" : {
"name" : "runPropertyName2",
"value" : "runPropertyValue2",
"encryptionType" : "NO_ENCRYPTION"
},
"runPropertyName1" : {
"name" : "runPropertyName1",
"value" : "runPropertyValue1",
"encryptionType" : "NO_ENCRYPTION"
}
},
"searchPath" : [ "object:!tenant:defaultTenant~directory:workspace-id" ],
"dataflowLocator" : "object:!tenant:defaultTenant~directory:workspace-id~graph:dataflowId",
"runAsUserLocator" : "object:!tenant:defaultTenant~user:userid"
}
}
}
Get a list of scheduled tasks
This API is deprecated and is superseded by version v4.
A GET
request returns a list of scheduled tasks.
Path Parameters
None
Request Parameters
Parameter | Description |
---|---|
|
The container locator of the requested scheduled tasks. |
|
Specifies the fields to return in the response. One or more of |
|
An optional FIQL filter expression. Supports searching by the 'name' attribute. For example |
|
The authentication token. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
The object resource locator of the requested scheduled task. |
|
|
Status of the response. One of: |
|
|
The identity of the scheduled task. It must be unique and will be allocated if not specified at creation. |
|
|
The name of the scheduled task. This must be unique in the container. |
|
|
The description of the scheduled task. |
|
|
true if schedule is enabled, defaults to true. |
|
|
The identity of the data flow to schedule. See dataflows. |
|
|
The search path is a list of workspaces to search when locating the data flow. See dataflows. |
|
|
A map of run properties. |
|
|
The name of the run property is used as the key to the run property details in the map. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
The name of the run property is used as the key to the run property details in the map. |
|
|
The name of the run property. |
|
|
The value of the run property. |
|
|
Trigger Properties e.g. 'cronExpression'. |
|
|
Quartz Cron Expression. |
|
|
The date and time when the schedule starts in ISO-8601 format. |
|
|
The date and time when the schedule ends in ISO-8601 format. |
|
|
The username that will run the schedule. |
Example request
GET /api/v3/simple-scheduled-tasks?container=object:!tenant:defaultTenant~directory:workspace-id&fields=object&filter=name%3D%3D'Schedule%20Name'<k=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2537
{
"status" : "OK",
"data" : {
"objects" : [ {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:scheduled-task-id-001",
"object" : {
"id" : "scheduled-task-id-001",
"name" : "First Scheduled Task",
"description" : "Schedule Description",
"enabled" : false,
"triggerProperties" : {
"cronExpression" : "0 00 00 1 1/1 ? *",
"startDateTime" : "Start Date is ISO 8601 format",
"endDateTime" : "Start Date is ISO 8601 format"
},
"runAs" : "runAsUsername",
"dataflowId" : "dataflowId",
"runProperties" : {
"runPropertyName2" : {
"name" : "runPropertyName2",
"value" : "runPropertyValue2",
"encryptionType" : "NO_ENCRYPTION"
},
"runPropertyName1" : {
"name" : "runPropertyName1",
"value" : "runPropertyValue1",
"encryptionType" : "NO_ENCRYPTION"
}
},
"searchPath" : [ "object:!tenant:defaultTenant~directory:workspace-id" ],
"dataflowLocator" : "object:!tenant:defaultTenant~directory:workspace-id~graph:dataflowId",
"runAsUserLocator" : "object:!tenant:defaultTenant~user:userid"
}
}, {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:scheduled-task-id-002",
"object" : {
"id" : "scheduled-task-id-002",
"name" : "Second Scheduled Task",
"description" : "Schedule Description",
"enabled" : false,
"triggerProperties" : {
"cronExpression" : "0 00 00 1 1/1 ? *",
"startDateTime" : "Start Date is ISO 8601 format",
"endDateTime" : "Start Date is ISO 8601 format"
},
"runAs" : "runAsUsername",
"dataflowId" : "dataflowId",
"runProperties" : {
"runPropertyName2" : {
"name" : "runPropertyName2",
"value" : "runPropertyValue2",
"encryptionType" : "NO_ENCRYPTION"
},
"runPropertyName1" : {
"name" : "runPropertyName1",
"value" : "runPropertyValue1",
"encryptionType" : "NO_ENCRYPTION"
}
},
"searchPath" : [ "object:!tenant:defaultTenant~directory:workspace-id" ],
"dataflowLocator" : "object:!tenant:defaultTenant~directory:workspace-id~graph:dataflowId",
"runAsUserLocator" : "object:!tenant:defaultTenant~user:userid"
}
} ]
}
}
Delete a simple scheduled task
This API is deprecated and is superseded by version v4.
A DELETE
request deletes a simple scheduled task.
Path Parameters
Parameter | Description |
---|---|
|
The locator of the scheduled task to delete. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
Request Fields
None
Response Fields
None
Example request
DELETE /api/v3/simple-scheduled-tasks/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:simple-scheduled-task-id?ltk=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 156
{
"status" : "OK",
"data" : {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:simple-scheduled-task-id"
}
}
Ad-hoc run of a simple scheduled task
This API is deprecated and is superseded by version v4.
A POST
request executes an ad-hoc run of a simple scheduled task.
Run property values can be overridden for this run only if required.
A failed execution plan state can be run again by specifying the execution plan state locator.
Path Parameters
Parameter | Description |
---|---|
|
The locator of the scheduled task to run. |
Request Parameters
Parameter | Description |
---|---|
|
The authentication token. |
Request Fields
Path | Type | Description |
---|---|---|
|
|
The locator for the execution plan state locator when re-running a failed execution plan state. |
|
|
A map of overridden run properties. |
|
|
The name of the run property is used as the key to the run property details in the map. |
|
|
The name of the run property. |
|
|
The overridden value of the run property. |
|
|
The name of the run property. |
|
|
The overridden value of the run property. |
|
|
The concurrent execution strategy. |
Response Fields
Path | Type | Description |
---|---|---|
|
|
Object resource locator. Used to identify the resource. |
|
|
Status of the response. One of: |
Example request
POST /api/v3/simple-scheduled-tasks/run-now/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:simple-scheduled-task-id?ltk=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded
ltk=AUTHENTICATION_TOKEN
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 156
{
"status" : "OK",
"data" : {
"locator" : "object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:simple-scheduled-task-id"
}
}
Example request to re-run failed task
POST /api/v3/simple-scheduled-tasks/run-now/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:simple-scheduled-task-id?ltk=AUTHENTICATION_TOKEN HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
Content-Length: 240
Host: localhost:8080
{"executionPlanStateLocator":"object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:simple-scheduled-task-idexecution-plan-state:execution-plan-state-id","overriddenRunProperties":null,"concurrentExecutionStrategy":null}
Example request to run with overridden run property values
POST /api/v3/simple-scheduled-tasks/run-now/object:!tenant:defaultTenant~directory:workspace-id~simple-scheduled-task:simple-scheduled-task-id?ltk=AUTHENTICATION_TOKEN HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
Content-Length: 407
Host: localhost:8080
{"executionPlanStateLocator":null,"overriddenRunProperties":{"runPropertyName2":{"name":"runPropertyName2","value":"overriddenrunPropertyValue2","source":null,"dataType":null,"editorData":null,"managementData":null},"runPropertyName1":{"name":"runPropertyName1","value":"overriddenrunPropertyValue1","source":null,"dataType":null,"editorData":null,"managementData":null}},"concurrentExecutionStrategy":null}
Errors
See errors for details of the error response.
Error Code | Description | Arguments |
---|---|---|
lae.scheduler.invalidCronExpression |
The specified |
|
lae.scheduler.missingCronExpression |
The |
|
lae.scheduler.scheduledTaskNameNotUnique |
The specified |
|
lae.scheduler.scheduledTaskNameNotSpecified |
The |
|
lae.scheduler.scheduledTaskIdNotSpecified |
The |
|
lae.scheduler.executionPlanStateRunning |
The scheduled task could not be deleted as it is currently running. |
|