Edit

Data Store REST API

The Data Store REST Service is used for remote DataStore management through WorkFusion application.

Generally, the REST service works with JSON data.

Configuration

important

To work with Data Stores, use the /soap/v1/datastores URL.

URL Examples

https://custom-name.workfusion.com/workfusion/soap/v1/datastores

API Security

All API postings are made over a Secure Sockets Layer (SSL) connection, which encrypts communications between the user and web server to ensure data remains private.

note

All requests must be preceding with https://.

WorkFusion REST API supports basic (login and password hash) authentication to ensure that APIs are only accessible to those with the proper credentials.

Basic authentication

• username: Your username in Control Tower.
• password: Hash of your password in Control Tower.

Using REST API with SSO

When using REST API with SSO you can not use your SSO ID or password. The recommended approach for using REST API with SSO enabled is the following:

1. Disable SSO: wf.sso.saml.enable=false
2. Restart Control Tower: wfmanager restart workfusion
3. Log in to Workfusion with pre-SSO ID and password.
4. Create a special REST API user and grant necessary permissions. Assign a proper role.
5. Enable SSO: wf.sso.saml.enable=true
6. Restart Control Tower: wfmanager restart workfusion
7. To log in, use the /workfusion/api/dologin enpoint. /workfusion/dologin is disabled once you turn on SSO.

Now, SSO is enabled, but you can use that REST API user id/password for REST API authentication.

Operations

Rules applied to the Data Store queries:

• Add the ds_ prefix to the Data Store name.

• If you have some UPPERCASE characters in the Data Store name, wrap the whole name in double quotes like this: "ds_01_WL_CL_HT_DD"

• Use the PostgreSQL syntax.

Request

Name	Resource Path	HttpMethod	Parameters	Example URL
Execute	/execute	POST	query (any kind of SQL query to execute) - required, query param	/soap/v1/datastores/select?query=DELETE FROM ds_testDataStore
Select	/select	GET	query (SQL select query) - required, query param; maxRows (fetch row count limit) - required, query param;	/soap/v1/datastores/select?query=SELECT * FROM "ds_testDataStore"&maxRows=5
CreateOrUpdate	/{name}/createOrUpdate	POST	{name} (DataStore name) required, path param; dataStoreData - required, body param, consits of: columns (Key-value map "name:type") - required; originalCampaignUuid - optional; automationUseCaseId - optional;	/soap/v1/datastores/testDataStore/createOrUpdate Body (Content-Type: application/json) { "columns": { "name":"TEXT" } }
Insert	/{name}/insert	POST	{name} (DataStore name) - required, path param; rowData - required, body param, consists of: headers (array) - required; values (array) - required;	/soap/v1/datastores/testDataStore/insert

Examples:

• CreateOrUpdate:

  /soap/v1/datastores/datastore_name/createOrUpdate
  

  Body:

  {
      "columns": {
          "name": "TEXT",
          "surname": "TEXT"
      }
  }
  

• Insert:

  /soap/v1/datastores/datastore_name/insert
  

  Body:

  {
      "headers": [
          "name",
          "surname"
      ],
      "values": [
          "value1",
          "value2"
      ]
  }
  

Response

Consists of three parts:

• responseStatus: "SUCCESS", "FAILURE"
• body: response data DTO
• errors: collection of business errors if a request fails

Examples:

/soap/v1/datastores/select?query=SELECT * FROM "ds_testDataStore"&maxRows=5

Success:

{
    "responseStatus": "SUCCESS",
    "body": {
        "rowData": [
            {
                "columnDescriptions": [
                    {
                        "type": 4,
                        "name": "ds_testDataStore_id"
                    },
                    {
                        "type": 12,
                        "name": "column1"
                    },
                    {
                        "type": 4,
                        "name": "column2"
                    }
                ],
                "rowData": [
                    1,
                    "value1",
                    5
                ]
            }
        ]
    },
    "errors": []
}

Failure:

{
    "responseStatus": "FAILURE",
    "body": null,
    "errors": [
        {
            "code": 0,
            "message": "StatementCallback; bad SQL grammar [SELECT * from \"ds_testDataStores\"]; nested exception is org.postgresql.util.PSQLException: error: relation \"ds_testDataStores\" doesn't exist\n  Position: 15"
        }
    ]
}

Access Data Store service in Manual Tasks

There is a possibility to insert Data Store REST API calls in Manual Tasks using AJAX.

In that case, the service URL is:

/workfusion/public/datastores

The security is provided by:

• Unique task hitId parameter
• Allowed Data Store queries set in Manual Task designer
• Task status that works only for active tasks