Introduction

Welcome to the Data3Sixty Analyze REST API guide.

The Data3Sixty Analyze REST API provides access to Data3Sixty 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 Data3Sixty Analyze API conventions and any variations from REST API conventions.

  • Definitions - Describes Data3Sixty 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

This version of the API is not backward-compatible with 3.1.x versions. Note the following changes:

  • All response formats have been standardized to return status, data and errors attributes in a consistent manner.

  • The format of the error responses has been enhanced. See errors.

  • The containerLocator request parameter has been renamed as container.

  • The metadata request parameter has been replaced by the fields request parameter. See Specifying fields to return.

  • The detail request parameter has been removed from the Data flows list API. Data flow details are always returned.

Data3Sixty Analyze REST API Conventions

HTTP verbs

Data3Sixty 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

GET

Used to retrieve a resource.

POST

Used to create a new resource.

PUT

Used to update an existing resource, full updates only.

DELETE

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

Data3Sixty Analyze REST API returns the following HTTP Status Codes:

HTTP Code Meaning Response Body

200

Success.

Depends on requested resource.

202

Still processing.

Body containing the asynchronous job id.

400

Request error.

Body containing the error information. See errors.

401

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. Data3Sixty 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. specifying fields=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

Data3Sixty Analyze Content Repository

The Data3Sixty Analyze Content Repository (DCR) stores Data3Sixty 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 Data3Sixty 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 Data3Sixty 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

status

String

The status of the response. It will be ERROR if there are any errors in the response.

errors

Array

An array of errors. A response may report multiple errors.

errors[0].locale

String

The locale used to render the message.

errors[0].errorCode

String

The error code uniquely identifies the error type.

errors[0].messages

Array

An array of messages associated with the error.

errors[0].messages[0].arguments

Array

An array of argument values related to the message.

errors[0].messages[0].arguments[0].value

String

The value of an argument.

errors[0].messages[0].messageKey

String

The message key uniquely identifies the message associated with the error.

errors[0].messages[0].message

String

The error message rendered in a readable format.

Example

HTTP/1.1 400 Bad Request
Content-Length: 413
Content-Type: application/json;charset=UTF-8

{
  "status" : "ERROR",
  "errors" : [ {
    "locale" : "en_US",
    "messages" : [ {
      "message" : "The object requested 'object:!tenant:defaultTenant~user:nouser' cannot be found.",
      "arguments" : [ {
        "value" : "object:!tenant:defaultTenant~user:nouser"
      } ],
      "messageKey" : "lae.collection.objectNotFoundError"
    } ],
    "errorCode" : "lae.collection.objectNotFoundError"
  } ]
}

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

data.flows[0].name

String

The name of the flow.

data.flows[0].entryPointUri

String

The URI to call to initiate the flow.

status

String

HTTP Status Code.

Example request

GET /api/v3/login/rest/flows HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Length: 152
Content-Type: application/json;charset=UTF-8

{"status":"OK","data":{"flows":[{"entryPointUri":"/login/ui/initial","name":"ui"},{"entryPointUri":"/api/v3/login/rest/tenant/methods","name":"rest"}]}}

Tenant Methods

When Data3Sixty 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 Data3Sixty 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

data.methods[0].name

String

The name of the tenant method.

data.methods[0].uri

Null

The URI of the tenant method.

status

String

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;charset=UTF-8
Content-Length: 68

{"status":"OK","data":{"methods":[{"name":"automatic","uri":null}]}}

Resolve Tenant Automatically

Using the Automatic Tenant Resolver, Data3Sixty 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

data.tenantLocator

String

The tenant that the authenticating user belongs to.

data.tenantAuthMethodsUri

String

The URI to retrieve the authentication methods supported by the tenant.

status

String

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-Length: 181
Content-Type: application/json;charset=UTF-8

{"status":"OK","data":{"tenantLocator":"object:!tenant:defaultTenant","tenantAuthMethodsUri":"/api/v3/login/rest/authentication/methods?tenantLocator=object:!tenant:defaultTenant"}}

User Session

To use the Data3Sixty 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.

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. Data3Sixty Analyze currently supports two authentication methods:

  • Username Password Authentication - the client passes a user name and password which is authenticated using Active Directory, LDAP, or Data3Sixty Analyze itself, depending on configuration.

  • Siteminder Single-Sign-On - Authentication is delegated to the Siteminder SSO gateway. Data3Sixty Analyze links the authenticated user to its corresponding Data3Sixty Analyze profile.

A GET request is used to retrieve the supported authentication methods.

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Response fields

Path Type Description

data.methods[0].name

String

The name of the method.

data.methods[0].initialUri

String

URI to call to initialisze the session.

data.methods[0].renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.methods[0].unlockUri

String

URI to call to unlock the session after locking due to timeout.

status

String

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-Length: 284
Content-Type: application/json;charset=UTF-8

{"status":"OK","data":{"methods":[{"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

tenantLocator

Tenant Locator

Request fields

Path Type Description

username

String

The username.

password

String

The password.

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

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
Content-Type: application/json;charset=UTF-8
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

ltk

token to renew

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Request fields

Path Type Description

username

String

The username.

password

String

The password.

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

HTTP Status Code.

Example request

POST /api/v3/login/rest/authentication/username-password/renew?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
Content-Length: 50
Host: localhost:8080
ltk: tokenToRenew

{ "username":"username","password":"userpassword"}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
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

ltk

token to unlock

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Request fields

Path Type Description

username

String

The username.

password

String

The password.

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

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
Content-Type: application/json;charset=UTF-8
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

ltk

token to logout

Request fields

None

Response fields

Path Type Description

status

String

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"}

Acquire an authentication token using Siteminder SSO Authentication

The Siteminder SSO User should be passed in the header. The default parameter name for the User is SM_USER. A GET request is used to acquire the token.

Request headers

Name Description

SM_USER

User name.

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Request fields

NONE

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

HTTP Status Code.

Example request

GET /api/v3/login/rest/authentication/siteminder-sso/initial?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
SM_USER: username
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Length: 258
Content-Type: application/json;charset=UTF-8

{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/siteminder-sso/unlock","renewUri":"/api/v3/login/rest/authentication/siteminder-sso/renew","logoutUri":"/api/v3/logout/rest/authentication/siteminder-sso/initial"}}

Renew a session using Siteminder SSO 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. The Siteminder SSO User should be passed in the header. The default parameter name for the User is SM_USER.

A `GET` request is used to renew the token.

Request headers

Name Description

ltk

Token to renew.

SM_USER

User name.

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Request fields

None

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

HTTP Status Code.

Example request

GET /api/v3/login/rest/authentication/siteminder-sso/renew?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
SM_USER: username
Host: localhost:8080
ltk: tokenToRenew

Example response

HTTP/1.1 200 OK
Content-Length: 258
Content-Type: application/json;charset=UTF-8

{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/siteminder-sso/unlock","renewUri":"/api/v3/login/rest/authentication/siteminder-sso/renew","logoutUri":"/api/v3/logout/rest/authentication/siteminder-sso/initial"}}

Unlock a session using Siteminder SSO 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.

The Siteminder SSO User should be passed in the header. The default parameter name for the User is SM_USER.

A GET request is used to unlock the token.

Request headers

Name Description

ltk

Token to unlock.

SM_USER

User name.

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Request fields

None

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

HTTP Status Code.

Example request

GET /api/v3/login/rest/authentication/siteminder-sso/unlock?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
SM_USER: username
ltk: tokenToUnlock
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Length: 258
Content-Type: application/json;charset=UTF-8

{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/siteminder-sso/unlock","renewUri":"/api/v3/login/rest/authentication/siteminder-sso/renew","logoutUri":"/api/v3/logout/rest/authentication/siteminder-sso/initial"}}

Release an authentication token using Siteminder SSO Authentication

A GET request is used to release the token.

Request headers

Name Description

ltk

Token to logout.

Request fields

None

Response fields

Path Type Description

status

String

HTTP Status Code.

Example request

GET /api/v3/logout/rest/authentication/siteminder-sso/initial HTTP/1.1
Content-Type: application/json;charset=UTF-8
SM_USER: username
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

Table 1. /api/v3/users/{locator}
Parameter Description

locator

The object resource locator of the requested user.

Request Parameters

Parameter Description

ltk

The authentication token.

fields

Specifies the fields to return in the response. One or more of objects or metadata. Defaults to objects

Response Fields

Path Type Description

data.locator

String

The object resource locator of the requested user.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

data.object.id

String

The identity of the user.

data.object.name

String

The name of the user.

data.object.tenant

String

The tenant the user belongs to.

data.object.active

Boolean

true if user is active.

data.object.state

String

One of ACTIVE, DEACTIVATED or DELETED. Deleted user profiles are kept in the system for auditing purposes.

data.object.imported

Boolean

true if user is imported e.g. from LDAP directory.

data.object.principalImportDetails

Null

If user is imported then this will contain details relevant to the import.

data.metadata

Object

Metadata for the resource.

data.metadata.locator

String

The resource locator that uniquely identifies the resource.

data.metadata.createdBy

String

The userid of the user that created the resource.

data.metadata.createdByName

String

The username of the user that created the resource.

data.metadata.createdOn

String

Creation time of resource in ISO-8601 format.

data.metadata.modifiedBy

String

The userid of the user that last modified the resource.

data.metadata.modifiedByName

String

The username of the user that last modified the resource.

data.metadata.modifiedOn

String

Last modification time of resource in ISO-8601 format.

data.metadata.containerLocator

String

The resource locator that uniquely identifies the container resource.

data.metadata.resourceId.objectType

String

The resource type.

data.metadata.resourceId.objectId

String

The resource id.

data.metadata.resourceId.universal

Boolean

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-Length: 1052
Content-Type: application/json;charset=UTF-8

{
  "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" : "2019-03-20T08:32:18+0000",
      "modifiedBy" : "modified-by-user-Id",
      "modifiedOn" : "2019-03-20T08:32:18+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
    }
  }
}

Get a list of users

GET request returns the list of users.

Path Parameters

None

Request Parameters

Parameter Description

container

The container locator of the requested users.

fields

Specifies the fields to return in the response. One or more of objects or metadata. Defaults to objects

filter

An optional FIQL filter expression. Supports searching by the 'name' attribute. For example filter=name=='Object Name'

ltk

The authentication token.

Response Fields

Path Type Description

data.objects[].locator

String

The object resource locator of the requested user.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

data.objects[].object.id

String

The identity of the user.

data.objects[].object.name

String

The name of the user.

data.objects[].object.tenant

String

The tenant the user belongs to.

data.objects[].object.active

Boolean

true if user is active.

data.objects[].object.state

String

One of ACTIVE, DEACTIVATED or DELETED. Deleted user profiles are kept in the system for auditing purposes.

data.objects[].object.imported

Boolean

true if user is imported e.g. from LDAP directory.

data.objects[].object.principalImportDetails

Null

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'&ltk=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Length: 747
Content-Type: application/json;charset=UTF-8

{
  "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
      }
    }, {
      "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
      }
    } ]
  }
}

User Preferences

Get the user preferences for a specified user

GET request returns the user preferences for the specified user.

Path Parameters

Table 2. /api/v3/users/{userLocator}/userpreferences
Parameter Description

userLocator

The user locator for the user whose preferences are requested .

Request Parameters

Parameter Description

ltk

The authentication token.

fields

Specifies the fields to return in the response. One or more of objects or metadata. Defaults to objects

Response Fields

Path Type Description

data.objects[].locator

String

The object resource locator of the requested user preferences.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

data.objects[].object.id

String

The identity of the user preference.

data.objects[].object.defaultSearchPathSet

String

The default search path set for the user.

data.objects[].object.storagePreference

Object

The user’s storage preferences.

data.objects[].object.storagePreference.defaultWorkspace

String

The object resource locator of the workspace where user generated artifacts are stored.

data.objects[].object.storagePreference.temporaryWorkspace

String

The object resource locator of the workspace where temporal user generated artifacts are stored. This is reserved for system use.

data.objects[].object.storagePreference.clipboardId

String

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-Length: 644
Content-Type: application/json;charset=UTF-8

{
  "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:df66ab34-fd08-4847-aaef-12fea260b3d5",
          "temporaryWorkspace" : "object:!tenant:defaultTenant~workspace:1d755efd-c38d-49b5-afea-1fae5c6108ab",
          "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, Data3Sixty 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

container

The container locator of the requested workspaces.

fields

Specifies the fields to return in the response. One or more of objects or metadata. Defaults to objects

filter

An optional FIQL filter expression. Supports searching by the 'name' attribute. For example filter=name=='Object Name'

ltk

The authentication token.

Response Fields

Path Type Description

data.objects[].locator

String

The object resource locator of the requested workspace.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

data.objects[].object.id

String

The identity of the workspace. It must be unique and will be allocated if not specified at creation.

data.objects[].object.name

String

The name of the workspace.

data.objects[].object.directory

String

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'&ltk=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
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

container

The container locator of the requested directories. This can be a tenant, workspace or directory.

fields

Specifies the fields to return in the response. One or more of objects or metadata. Defaults to objects

filter

An optional FIQL filter expression. Supports searching by the 'name' attribute. For example filter=name=='Object Name'

ltk

The authentication token.

Response Fields

Path Type Description

data.objects[].locator

String

The object resource locator of the requested directory.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

data.objects[].object.id

String

The identity of the directory. It must be unique and will be allocated if not specified at creation.

data.objects[].object.name

String

The name of the directory.

data.objects[].object.description

String

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'&ltk=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Length: 529
Content-Type: application/json;charset=UTF-8

{
  "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

container

The container locator of the requested data flows.

fields

Specifies the fields to return in the response. One or more of objects or metadata. Defaults to objects

filter

An optional FIQL filter expression. Supports searching by the 'name' attribute. For example filter=name=='Object Name'

ltk

The authentication token.

Response Fields

Path Type Description

data.objects[].locator

String

The object resource locator of the requested data flow.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

data.objects[].object.id

String

The identity of the data flow.

data.objects[].object.name

String

The name of the data flow.

data.objects[].object.searchPathSet

String

Object resource locator identifying the search path that the dataflow uses to locate nodes it references.

data.objects[].object.runProperties

Object

A map of run property definitions for the data flow.

data.objects[].object.runProperties.Run Property Name

Object

The run property name is used as the key.

data.objects[].object.runProperties.Run Property Name.name

String

Name of the run property. This should be used when setting the run property value.

data.objects[].object.runProperties.Run Property Name.dataType

String

The run property type.

data.objects[].object.runProperties.Run Property Name.visibility

Number

The visibility level of the run property.

data.objects[].object.runProperties.Run Property Name.runParameter

Boolean

Indicates that the property is a run property. This is called runParameter for legacy reasons.

data.objects[].object.runProperties.Run Property Name.documentation

String

Documentation for the run property.

data.objects[].object.runProperties.Run Property Name.values

Array

For property definitions of type choice this is an array of the allowed values.

data.objects[].object.runProperties.Run Property Name.validators

Array

Reserved for future use.

data.objects[].object.runProperties.Run Property Name.defaultSource

String

Reserved for future use.

data.objects[].object.runProperties.Run Property Name.sources

Array

Reserved for future use.

data.objects[].object.runProperties.Run Property Name.currentEditor

String

Reserved for future use.

data.objects[].object.runProperties.Run Property Name.editors

Array

Reserved for future use.

data.objects[].object.runProperties.Run Property Name.associatedInputs

Array

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'&ltk=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
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

Table 3. /api/v3/dataflows/{locator}
Parameter Description

locator

The object resource locator of the requested data flow.

Request Parameters

Parameter Description

ltk

The authentication token.

fields

Specifies the fields to return in the response. One or more of objects or metadata. Defaults to objects

Response Fields

Path Type Description

data.locator

String

The object resource locator of the requested data flow.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

data.object.id

String

The identity of the data flow.

data.object.name

String

The name of the data flow.

data.object.searchPathSet

String

Object resource locator identifying the search path that the dataflow uses to locate nodes it references.

data.object.runProperties

Object

A map of run property definitions for the data flow.

data.object.runProperties.Run Property Name

Object

The run property name is used as the key.

data.object.runProperties.Run Property Name.name

String

Name of the run property. This should be used when setting the run property value.

data.object.runProperties.Run Property Name.dataType

String

The run property type.

data.object.runProperties.Run Property Name.visibility

Number

The visibility level of the run property.

data.object.runProperties.Run Property Name.runParameter

Boolean

Indicates that the property is a run property. This is called runParameter for legacy reasons.

data.object.runProperties.Run Property Name.documentation

String

Documentation for the run property.

data.object.runProperties.Run Property Name.values

Array

For property definitions of type choice this is an array of the allowed values.

data.object.runProperties.Run Property Name.validators

Array

Reserved for future use.

data.object.runProperties.Run Property Name.defaultSource

String

Reserved for future use.

data.object.runProperties.Run Property Name.sources

Array

Reserved for future use.

data.object.runProperties.Run Property Name.currentEditor

String

Reserved for future use.

data.object.runProperties.Run Property Name.editors

Array

Reserved for future use.

data.object.runProperties.Run Property Name.associatedInputs

Array

Reserved for future use.

data.metadata

Object

Metadata for the resource.

data.metadata.locator

String

The resource locator that uniquely identifies the resource.

data.metadata.createdBy

String

The userid of the user that created the resource.

data.metadata.createdByName

String

The username of the user that created the resource.

data.metadata.createdOn

String

Creation time of resource in ISO-8601 format.

data.metadata.modifiedBy

String

The userid of the user that last modified the resource.

data.metadata.modifiedByName

String

The username of the user that last modified the resource.

data.metadata.modifiedOn

String

Last modification time of resource in ISO-8601 format.

data.metadata.containerLocator

String

The resource locator that uniquely identifies the container resource.

data.metadata.resourceId.objectType

String

The resource type.

data.metadata.resourceId.objectId

String

The resource id.

data.metadata.resourceId.universal

Boolean

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;charset=UTF-8
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" : "2019-03-20T08:32:17+0000",
      "modifiedBy" : "modified-by-user-Id",
      "modifiedOn" : "2019-03-20T08:32:17+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

container

The container locator of the requested scheduled tasks.

ltk

The authentication token.

Request Fields

Path Type Description

id

String

The identity of the scheduled task. It must be unique and will be allocated if not specified at creation.

name

String

The name of the scheduled task. This must be unique in the container.

description

String

The description of the scheduled task.

enabled

Boolean

true if schedule is enabled, defaults to true.

dataflowId

String

The identity of the data flow to schedule. See dataflows.

searchPath

Array

The search path is a list of workspaces to search when locating the data flow. See dataflows.

runProperties

Object

A map of run properties.

runProperties.runPropertyName1

Object

The name of the run property is used as the key to the run property details in the map.

runProperties.runPropertyName1.name

String

The name of the run property.

runProperties.runPropertyName1.value

String

The value of the run property.

runProperties.runPropertyName2

Object

The name of the run property is used as the key to the run property details in the map.

runProperties.runPropertyName2.name

String

The name of the run property.

runProperties.runPropertyName2.value

String

The value of the run property.

triggerProperties

Object

Trigger Properties e.g. 'cronExpression'.

triggerProperties.cronExpression

String

Quartz Cron Expression.

triggerProperties.startDateTime

String

The date and time when the schedule starts in ISO-8601 format.

triggerProperties.endDateTime

String

The date and time when the schedule ends in ISO-8601 format.

runAs

String

The username that will run the schedule.

Response Fields

Path Type Description

data.locator

String

Object resource locator. Used to identify the resource.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

Example request

POST /api/v3/simple-scheduled-tasks?container=object:!tenant:defaultTenant~directory:workspace-id&ltk=AUTHENTICATION_TOKEN HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
Content-Length: 549
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"},"runPropertyName1":{"name":"runPropertyName1","value":"runPropertyValue1"}},"searchPath":["object:!tenant:defaultTenant~directory:workspace-id"]}

Example response

HTTP/1.1 200 OK
Content-Length: 161
Content-Type: application/json;charset=UTF-8

{
  "status" : "OK",
  "data" : {
    "locator" : "object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:44a66366-40a8-499c-ba25-2b9567dbc87e"
  }
}

Update a simple scheduled task

A PUT request updates a simple scheduled task.

Path Parameters

Table 4. /api/v3/simple-scheduled-tasks/{scheduledTaskLocator}
Parameter Description

scheduledTaskLocator

The locator for the scheduled task to update.

Request Parameters

Parameter Description

ltk

The authentication token.

Request Fields

Path Type Description

id

String

The identity of the scheduled task. It must be unique and will be allocated if not specified at creation.

name

String

The name of the scheduled task. This must be unique in the container.

description

String

The description of the scheduled task.

enabled

Boolean

true if schedule is enabled, defaults to true.

dataflowId

String

The identity of the data flow to schedule. See dataflows.

searchPath

Array

The search path is a list of workspaces to search when locating the data flow. See dataflows.

runProperties

Object

A map of run properties.

runProperties.runPropertyName1

Object

The name of the run property is used as the key to the run property details in the map.

runProperties.runPropertyName1.name

String

The name of the run property.

runProperties.runPropertyName1.value

String

The value of the run property.

runProperties.runPropertyName2

Object

The name of the run property is used as the key to the run property details in the map.

runProperties.runPropertyName2.name

String

The name of the run property.

runProperties.runPropertyName2.value

String

The value of the run property.

triggerProperties

Object

Trigger Properties e.g. 'cronExpression'.

triggerProperties.cronExpression

String

Quartz Cron Expression.

triggerProperties.startDateTime

String

The date and time when the schedule starts in ISO-8601 format.

triggerProperties.endDateTime

String

The date and time when the schedule ends in ISO-8601 format.

runAs

String

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: 549
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"},"runPropertyName1":{"name":"runPropertyName1","value":"runPropertyValue1"}},"searchPath":["object:!tenant:defaultTenant~directory:workspace-id"]}

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
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

A GET request returns the specified scheduled task.

Path Parameters

Table 5. /api/v3/simple-scheduled-tasks/{locator}
Parameter Description

locator

The object resource locator of the requested scheduled task.

Request Parameters

Parameter Description

ltk

The authentication token.

fields

Specifies the fields to return in the response. One or more of objects or metadata. Defaults to objects

Response Fields

Path Type Description

data.locator

String

The object resource locator of the requested scheduled task.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

data.object.id

String

The identity of the scheduled task. It must be unique and will be allocated if not specified at creation.

data.object.name

String

The name of the scheduled task. This must be unique in the container.

data.object.description

String

The description of the scheduled task.

data.object.enabled

Boolean

true if schedule is enabled, defaults to true.

data.object.dataflowId

String

The identity of the data flow to schedule. See dataflows.

data.object.searchPath

Array

The search path is a list of workspaces to search when locating the data flow. See dataflows.

data.object.runProperties

Object

A map of run properties.

data.object.runProperties.runPropertyName1

Object

The name of the run property is used as the key to the run property details in the map.

data.object.runProperties.runPropertyName1.name

String

The name of the run property.

data.object.runProperties.runPropertyName1.value

String

The value of the run property.

data.object.runProperties.runPropertyName2

Object

The name of the run property is used as the key to the run property details in the map.

data.object.runProperties.runPropertyName2.name

String

The name of the run property.

data.object.runProperties.runPropertyName2.value

String

The value of the run property.

data.object.triggerProperties

Object

Trigger Properties e.g. 'cronExpression'.

data.object.triggerProperties.cronExpression

String

Quartz Cron Expression.

data.object.triggerProperties.startDateTime

String

The date and time when the schedule starts in ISO-8601 format.

data.object.triggerProperties.endDateTime

String

The date and time when the schedule ends in ISO-8601 format.

data.object.runAs

String

The username that will run the schedule.

data.metadata

Object

Metadata for the resource.

data.metadata.locator

String

The resource locator that uniquely identifies the resource.

data.metadata.createdBy

String

The userid of the user that created the resource.

data.metadata.createdByName

String

The username of the user that created the resource.

data.metadata.createdOn

String

Creation time of resource in ISO-8601 format.

data.metadata.modifiedBy

String

The userid of the user that last modified the resource.

data.metadata.modifiedByName

String

The username of the user that last modified the resource.

data.metadata.modifiedOn

String

Last modification time of resource in ISO-8601 format.

data.metadata.containerLocator

String

The resource locator that uniquely identifies the container resource.

data.metadata.resourceId.objectType

String

The resource type.

data.metadata.resourceId.objectId

String

The resource id.

data.metadata.resourceId.universal

Boolean

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-Length: 1773
Content-Type: application/json;charset=UTF-8

{
  "status" : "OK",
  "data" : {
    "metadata" : {
      "createdByName" : "Created By User Name",
      "modifiedByName" : "Modified By User Name",
      "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" : "2019-03-20T08:32:18+0000",
      "modifiedBy" : "modified-by-user-Id",
      "modifiedOn" : "2019-03-20T08:32:18+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" ]
    }
  }
}

Get a list of scheduled tasks

A GET request returns a list of scheduled tasks.

Path Parameters

None

Request Parameters

Parameter Description

container

The container locator of the requested scheduled tasks.

fields

Specifies the fields to return in the response. One or more of objects or metadata. Defaults to objects

filter

An optional FIQL filter expression. Supports searching by the 'name' attribute. For example filter=name=='Object Name'

ltk

The authentication token.

Response Fields

Path Type Description

data.objects[].locator

String

The object resource locator of the requested scheduled task.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

data.objects[].object.id

String

The identity of the scheduled task. It must be unique and will be allocated if not specified at creation.

data.objects[].object.name

String

The name of the scheduled task. This must be unique in the container.

data.objects[].object.description

String

The description of the scheduled task.

data.objects[].object.enabled

Boolean

true if schedule is enabled, defaults to true.

data.objects[].object.dataflowId

String

The identity of the data flow to schedule. See dataflows.

data.objects[].object.searchPath

Array

The search path is a list of workspaces to search when locating the data flow. See dataflows.

data.objects[].object.runProperties

Object

A map of run properties.

data.objects[].object.runProperties.runPropertyName1

Object

The name of the run property is used as the key to the run property details in the map.

data.objects[].object.runProperties.runPropertyName1.name

String

The name of the run property.

data.objects[].object.runProperties.runPropertyName1.value

String

The value of the run property.

data.objects[].object.runProperties.runPropertyName2

Object

The name of the run property is used as the key to the run property details in the map.

data.objects[].object.runProperties.runPropertyName2.name

String

The name of the run property.

data.objects[].object.runProperties.runPropertyName2.value

String

The value of the run property.

data.objects[].object.triggerProperties

Object

Trigger Properties e.g. 'cronExpression'.

data.objects[].object.triggerProperties.cronExpression

String

Quartz Cron Expression.

data.objects[].object.triggerProperties.startDateTime

String

The date and time when the schedule starts in ISO-8601 format.

data.objects[].object.triggerProperties.endDateTime

String

The date and time when the schedule ends in ISO-8601 format.

data.objects[].object.runAs

String

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'&ltk=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2191

{
  "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" ]
      }
    }, {
      "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" ]
      }
    } ]
  }
}

Delete a simple scheduled task

A DELETE request deletes a simple scheduled task.

Path Parameters

Table 6. /api/v3/simple-scheduled-tasks/{scheduledTaskLocator}
Parameter Description

scheduledTaskLocator

The locator of the scheduled task to delete.

Request Parameters

Parameter Description

ltk

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;charset=UTF-8
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

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

Table 7. /api/v3/simple-scheduled-tasks/run-now/{scheduledTaskLocator}
Parameter Description

scheduledTaskLocator

The locator of the scheduled task to run.

Request Parameters

Parameter Description

ltk

The authentication token.

Request Fields

Path Type Description

executionPlanStateLocator

String

The locator for the execution plan state locator when re-running a failed execution plan state.

overriddenRunProperties

Object

A map of overridden run properties.

overriddenRunProperties.runPropertyName1

Object

The name of the run property is used as the key to the run property details in the map.

overriddenRunProperties.runPropertyName1.name

String

The name of the run property.

overriddenRunProperties.runPropertyName1.value

String

The overridden value of the run property.

overriddenRunProperties.runPropertyName2.name

String

The name of the run property.

overriddenRunProperties.runPropertyName2.value

String

The overridden value of the run property.

concurrentExecutionStrategy

String

The concurrent execution strategy. SKIP means that the run will be skipped if a run is already in progress for this schedule, RUN_CONCURRENTLY means that multiple runs can take place at the same time. The default value is SKIP.

Response Fields

Path Type Description

data.locator

String

Object resource locator. Used to identify the resource.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

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;charset=UTF-8
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-Length: 240
Content-Type: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
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
Host: localhost:8080
Content-Length: 267

{"executionPlanStateLocator":null,"overriddenRunProperties":{"runPropertyName2":{"name":"runPropertyName2","value":"overriddenrunPropertyValue2"},"runPropertyName1":{"name":"runPropertyName1","value":"overriddenrunPropertyValue1"}},"concurrentExecutionStrategy":null}

Errors

See errors for details of the error response.

Error Code Description Arguments

lae.scheduler.invalidCronExpression

The specified cronExpression does not conform to the Quartz Cron Expression format.

  • Specified cronExpression

lae.scheduler.missingCronExpression

The cronExpression attribute is not specified.

lae.scheduler.scheduledTaskNameNotUnique

The specified name attribute is not unique.

  • The specified name

lae.scheduler.scheduledTaskNameNotSpecified

The name attribute is not specified.

lae.scheduler.scheduledTaskIdNotSpecified

The id attribute is not specified. id is mandatory for update.

lae.scheduler.executionPlanStateRunning

The scheduled task could not be deleted as it is currently running.

  • Object Resource Locator of the running executon plan state.

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

Table 8. /api/v3/execution-plan-states/{locator}
Parameter Description

locator

The object resource locator of the requested execution plan state.

Request Parameters

Parameter Description

ltk

The authentication token.

fields

Specifies the fields to return in the response. One or more of objects or metadata. Defaults to objects

Response Fields

Path Type Description

data.locator

String

The object resource locator of the requested execution plan state.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

data.object.id

String

The identity of the execution plan state.

data.object.status

String

The status of the execution plan state. Can be one of RUNNING, SKIPPED, COMPLETED, COMPLETED_WITH_ERRORS or CANCELED.

data.object.executionPlanLocator

String

The Object Resource Locator of the Execution Plan. For future use.

data.object.planState

Array

The plan state. For future use.

data.object.startTime

String

The start time of the first execution of this execution plan state in ISO-8601 format.

data.object.endTime

String

The end time of the last execution of this execution plan state in ISO-8601 format.

data.object.durationInSeconds

Number

The total duration in seconds of all executions of this execution plan state.

data.object.errorResponse

Null

Error details in the case of an unsuccessful execution.

data.metadata

Object

Metadata for the resource.

data.metadata.locator

String

The resource locator that uniquely identifies the resource.

data.metadata.createdBy

String

The userid of the user that created the resource.

data.metadata.createdByName

String

The username of the user that created the resource.

data.metadata.createdOn

String

Creation time of resource in ISO-8601 format.

data.metadata.modifiedBy

String

The userid of the user that last modified the resource.

data.metadata.modifiedByName

String

The username of the user that last modified the resource.

data.metadata.modifiedOn

String

Last modification time of resource in ISO-8601 format.

data.metadata.containerLocator

String

The resource locator that uniquely identifies the container resource.

data.metadata.resourceId.objectType

String

The resource type.

data.metadata.resourceId.objectId

String

The resource id.

data.metadata.resourceId.universal

Boolean

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;charset=UTF-8
Content-Length: 1567

{
  "status" : "OK",
  "data" : {
    "metadata" : {
      "createdByName" : "Created By User Name",
      "modifiedByName" : "Modified By User Name",
      "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" : "2019-03-20T08:32:17+0000",
      "modifiedBy" : "modified-by-user-Id",
      "modifiedOn" : "2019-03-20T08:32:17+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",
      "status" : "COMPLETED",
      "startTime" : "2019-03-20T08:30:17+0000",
      "endTime" : "2019-03-20T08:32:17+0000",
      "durationInSeconds" : 120,
      "executionPlanLocator" : "object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:scheduled-task-id~execution-plan:execution-plan-id",
      "planState" : [ {
        "executionPlanNodeId" : "7c881b47-bc97-4d63-8a5f-a40549f909c3",
        "executionSession" : "object:!tenant:defaultTenant~directory:workspace-id~execution-session:execution-session-id",
        "overriddenRunProperties" : null
      } ],
      "errorResponse" : null
    }
  }
}

Get a list of execution plan states

GET request returns the list of execution plan states.

Path Parameters

None

Request Parameters

Parameter Description

container

The container locator of the requested execution plan states.

fields

Specifies the fields to return in the response. One or more of objects or metadata. Defaults to objects

filter

An optional FIQL filter expression. Supports searching by the 'name' attribute. For example filter=name=='Object Name'

ltk

The authentication token.

Response Fields

Path Type Description

data.objects[].locator

String

The object resource locator of the requested execution plan state.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

data.objects[].object.id

String

The identity of the execution plan state.

data.objects[].object.status

String

The status of the execution plan state. Can be one of RUNNING, SKIPPED, COMPLETED, COMPLETED_WITH_ERRORS or CANCELED.

data.objects[].object.executionPlanLocator

String

The Object Resource Locator of the Execution Plan. For future use.

data.objects[].object.planState

Array

The plan state. For future use.

data.objects[].object.startTime

String

The start time of the first execution of this execution plan state in ISO-8601 format.

data.objects[].object.endTime

String

The end time of the last execution of this execution plan state in ISO-8601 format.

data.objects[].object.durationInSeconds

Number

The total duration in seconds of all executions of this execution plan state.

data.objects[].object.errorResponse

Null

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'&ltk=AUTHENTICATION_TOKEN HTTP/1.1
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1724

{
  "status" : "OK",
  "data" : {
    "objects" : [ {
      "locator" : "object:!tenant:defaultTenant~directory:workspace-id~executionplanstate:execution-plan-state-id-001",
      "object" : {
        "id" : "execution-plan-state-id-001",
        "status" : "COMPLETED",
        "startTime" : "2019-03-20T08:30:17+0000",
        "endTime" : "2019-03-20T08:32:17+0000",
        "durationInSeconds" : 120,
        "executionPlanLocator" : "object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:scheduled-task-id~execution-plan:execution-plan-id",
        "planState" : [ {
          "executionPlanNodeId" : "d20fc961-63e7-4390-9cd3-1839dfa549b6",
          "executionSession" : "object:!tenant:defaultTenant~directory:workspace-id~execution-session:execution-session-id",
          "overriddenRunProperties" : null
        } ],
        "errorResponse" : null
      }
    }, {
      "locator" : "object:!tenant:defaultTenant~directory:workspace-id~executionplanstate:execution-plan-state-id-002",
      "object" : {
        "id" : "execution-plan-state-id-002",
        "status" : "COMPLETED",
        "startTime" : "2019-03-20T08:30:17+0000",
        "endTime" : "2019-03-20T08:32:17+0000",
        "durationInSeconds" : 120,
        "executionPlanLocator" : "object:!tenant:defaultTenant~directory:workspace-id~scheduled-task:scheduled-task-id~execution-plan:execution-plan-id",
        "planState" : [ {
          "executionPlanNodeId" : "0bb6e84f-0a8a-4d0a-aa3d-04769dbbee96",
          "executionSession" : "object:!tenant:defaultTenant~directory:workspace-id~execution-session:execution-session-id",
          "overriddenRunProperties" : null
        } ],
        "errorResponse" : null
      }
    } ]
  }
}

Delete an execution plan state

A DELETE request deletes an execution plan state.

Path Parameters

Table 9. /api/v3/execution-plan-states/{executionPlanStateLocator}
Parameter Description

executionPlanStateLocator

The locator of the execution plan state to delete.

Request Parameters

Parameter Description

ltk

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-Length: 187
Content-Type: application/json;charset=UTF-8

{
  "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

destinationLocator

Target workspace or directory locator.

file

Filename of LNA to import.

shouldOverwrite

If set to true, existing items at the target location with the same name or id will be overwritten.

ignoreErrors

If set to true, items will be imported even if they have missing dependencies.

ltk

The authentication token.

Response Fields

Path Type Description

data.totalErrorCount

Number

Total error count for imported items.

data.importedItems

Object

A map containing imported items and the status of the import for each item.

data.importedItems.object:!edit-session:id~graph:id.id

String

Import item status id. In these examples the id is object:!edit-session:id~graph:id

data.importedItems.object:!edit-session:id~graph:id.destinationLocator

String

The object resource locator for the imported item. This is where the item is located in the system.

data.importedItems.object:!edit-session:id~graph:id.conflictingItemName

String

The name of the conflicting item when the import of this item has failed due to an id or name conflict.

data.importedItems.object:!edit-session:id~graph:id.saveItemName

String

The name of this item when the import of this item has failed due to an id conflict.

data.importedItems.object:!edit-session:id~graph:id.status

String

The import item status. Can be one of SUCCESS, ID_CONFLICT_DETECTED, NAME_CONFLICT_DETECTED, SKIPPED, ERROR.

data.importedItems.object:!edit-session:id~graph:id.resolutionCompilationErrorCount

Number

The total number of resoultion and compilation errors in the imported items.

status

String

Status of the response. One of: OK, ERROR, SKIPPED or ASYNC

Example request

POST /api/v3/lna/import?destinationLocator=object:!tenant:defaultTenant~directory:workspace-id&file=Dataflow.lna&shouldOverwrite=true&ignoreErrors=false&ltk=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;charset=UTF-8
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:

  1. Get the login flow entry point URI for the client type. REST API clients use the rest login flow.

  2. Use the rest login flow entryPointUri to get the tenant methods that can be used to identify the tenant that the user belongs to.

  3. 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 locator object:!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.

  4. Using the tenant locator, get the authentication methods to identify the authentication methods supported by the tenant. Data3Sixty Analyze currently supports two authentication methods - Username-Password and Siteminder Single-Sign-On. These methods may be made available via configuration and licensing. If the system is not configured to support Siteminder SSO then this step may be skipped and the Username-Password authentication APIs used directly.

  5. 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.

  6. On completion of activity logout of the session using the appropriate logout API for the authentication method.

Note that when using Siteminder SSO, the SM_USER must be included in the header of every API request.

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.

<tenantLocator>~directory:__Root__ e.g. object:!tenant:defaultTenant~directory:__Root__

USERS

Directory containing all the users' personal directories (My Documents).

<tenantLocator>~directory:__Root__~directory:__Users__ e.g. object:!tenant:defaultTenant~directory:__Root__~directory:__Users__

Public Documents

Directory containing shared artifacts.

<tenantLocator>~directory:__Root__~directory:lavastorm~directory:shared e.g. object:!tenant:defaultTenant~directory:__Root__~directory:lavastorm~directory:shared

Data3Sixty Nodes

Directory containing system-defined nodes.

<tenantLocator>~directory:__Root__~directory:lavastorm~directory:shared e.g. object:!tenant:defaultTenant~directory:__Root__~directory:lavastorm~directory:internal

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:

  1. Retrieve the user locator for the user using the users API. Filter by name and set fields=object,metadata. The locator is returned as part of the metadata.

  2. 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

  1. Obtain an authentication token. See User Session. You will need to use this authentication token in all subsequent requests.

  2. 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:

    1. Retrieve the user locator for the user using the users API. Filter by name and set fields=object,metadata. The locator is returned as part of the metadata.

    2. Retrieve the workspace locator for the specified user using the user preferences API. Use the user locator as the path parameter.

  3. Retrieve the id and containerLocator for the data flow you wish to schedule using the data flows API. Filter by name and set fields=object,metadata.

  4. 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 id as dataflowId and include the containerLocator for the data flow in the searchPath. Set run property values 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:

  1. Obtain an authentication token. See User Session.

  2. 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 Data3Sixty 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.

  1. 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.

  2. 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.

  1. Follow the steps in retrieve schedule run status with the fields=object,metadata field specified to identify the executionPlanStateLocator of the failed run.

  2. 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.