Automated Workflows (REST)

The Automated Workflows REST service allows developers to integrate with the automated workflows framework to programmatically register actions, register triggers and send triggers. Review the content in Fundamentals of automated workflows before you start writing code to interact with automated workflows.

You can find the REST Service reference documentation and download the OAS specification file in this topic. You can also interact with automated workflows through the .NET API. See Automated Workflows API.

URLs

The URLs for REST endpoints contain path parameters that you need to set before making a call:

  • Set the {versionNumber} placeholder to the version of the REST API that you want to use, using the format lowercase v and the version number, for example v1.
  • Set other path parameters in the URLs to the Artifact ID of a given entity, for example setting {workspaceID} to the Artifact ID of a workspace.
    • To indicate the admin-level context, set the {workspaceID} path parameter to -1.
  • The x-csrf-header header is required for Kepler Calls. Use a dash (-) as the value for the x-csrf-header

Methods

  • workspaces//notifiers/trigger (POST): Notifies the given workspace a trigger has happened
  • workspaces//actions (GET): List Actions in a Workspace
  • workspaces//actions (PUT): Creates or Updates an Action
  • workspaces//triggers (GET): List Triggers in a Workspace
  • workspaces//triggers (PUT): Creates or Updates a Trigger
  • language/expressions/run (POST): Run/Debug Language Expression

Examples

Create a client in .NET to interact with the REST Service

This code sample illustrates how to create a client in .NET to interact with the REST Service, in this case to send a trigger via the REST endpoint

Copy 
public async Task <bool> SendTrigger()
{
    const int workspaceID = 405786;
    JToken result;

    using (var client = new HttpClient())
    {
        client.DefaultRequestHeaders.Add("X-CSRF-Header","-");
        client.DefaultRequestHeaders.Add("Authorization", "Basic " + Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes("test@test.com:SomePassword")));
        client.DefaultRequestHeaders.Add("X-Kepler-Version", "2.0");
        client.BaseAddress = new Uri("[https://localhost/](https://localhost/)");

        var sendTrigger = new SendTriggerBody
        {
            ID = "my-company/on-example-added",
            Version = 1,
            Message = "A Message",
            State = "complete",
            Inputs = new List<TriggerInput>
            {
                new TriggerInput
                {
                    ID = "type",
                    Value = "processing"
                }
            }
        };

        var jsonString = JsonConvert.SerializeObject(sendTrigger);

        var url = $"/Relativity.REST/API/relativity-automated-workflows/{versionNumber}/workspaces/{workspaceID}/notifiers/trigger";

        HttpResponseMessage response = await client.PostAsync(url, new StringContent(jsonString, Encoding.UTF8, "application/json"));

        switch (response.StatusCode) {
            case HttpStatusCode.OK:
            // success;
            break;
            case HttpStatusCode.BadRequest:
            // problem with the payload/request
            break;
            case HttpStatusCode.Unauthorized:
            // check your Authorization Header
            break;
            case HttpStatusCode.InternalServerError:
            // check your payload or unexpected error
            break;
            default:
            break;
        }

        var content = await response.Content.ReadAsStringAsync();

        result = JToken.Parse(content);
    }

  return result["Success"].Value <bool> ();
}

List Triggers

Use this endpoint to return a list of triggers. The JSON Request is empty for this call.

GET: {{host}}/Relativity.REST/api/relativity-automated-workflows/{versionNumber}/workspaces/{workspaceID}/triggers

JSON response

Copy 
{
  "Result": [
    {
      "Label": "Example Completed",
      "ID": "my-company/on-example-completed",
      "Group": "Search",
      "Version": 1,
      "Inputs" : [
        {
          "Label": "Report",
          "ID": "report-id",
          "UIElementType": "Dropdown",
          "ObjectManagerQueryInputSource": {
            "LabelFieldName": "Name",
            "ValueFieldName": "ArtifactID",
            "Guid": "481e9acf-368b-4341-b6b5-a21153ad9950"
          }
        }
      ],
      "States": [
        "complete",
        "complete-with-errors",
        "error",
        "canceled"
      ],
      "SelectableAsInitialTrigger": true
    }
  ],
  "Success": true,
  "Messages": []
}

Create or Update a Trigger

PUT: {{host}}/Relativity.REST/api/relativity-automated-workflows/{versionNumber}/workspaces/{workspaceID}/triggers

JSON request

Copy 
{
  "body": {
    "Group": "Other",
    "Label": "Example Added",
    "ID": "my-company/on-example-added-2",
    "Version": 1,
    "Inputs": [
      {
        "Label": "Type(s)",
        "ID": "type",
        "DefaultValue": "__Example__",
        "UIElementType": "MultiCheckbox",
        "InputSources": [
          {
            "Label": "Processing Set",
            "Value": "processing"`
          },
          {
            "Label": "Desktop Client (RDC)",
            "Value": "rdc",
            "Children": [
              {
                "ID": "rdc-choices",
                "UIElementType": "MultiCheckbox",
                "InputSources": [
                  {
                    "Label": "Document/Natives",
                    "Value": "rdc-documents"`
                  },
                  {
                    "Label": "Images",
                    "Value": "rdc-images"`
                  },
                  {
                    "Label": "Productions",
                    "Value": "rdc-productions"`
                  }
                ],
                "Properties": {}
              }
            ]
          },
          {
            "Label": "Integration Points (RIP)",
            "Value": "rip"`
          },
          {
            "Label": "Third Party (Import API)",
            "Value": "third-party"`
          }
        ],
        "Properties": {}
      }
    ],
    "States": [
      "complete",
      "complete-with-errors",
      "error",
      "canceled"
    ],
    "SelectableAsInitialTrigger": true
  }
}

JSON response

Copy 
{
  "Result": {
    "Label": "Example Added",
    "ID": "my-company/on-example-added-2",
    "Group": "Other",
    "Version": 1,
    "Inputs": [
      {
        "Label": "Type(s)",
        "ID": "type",
        "DefaultValue": "__Example__",
        "UIElementType": "MultiCheckbox",
        "InputSources": [
          {
            "Label": "Processing Set",
            "Value": "processing"
          },
          {
            "Label": "Desktop Client (RDC)",
            "Value": "rdc",
            "Children": [
              {
                "ID": "rdc-choices",
                "UIElementType": "MultiCheckbox",
                "InputSources": [
                  {
                    "Label": "Document/Natives",
                    "Value": "rdc-documents"
                  },
                  {
                    "Label": "Images",
                    "Value": "rdc-images"
                  },
                  {
                    "Label": "Productions",
                    "Value": "rdc-productions"
                  }
                ],
                "Properties": {}
              }
            ]
          },
          {
            "Label": "Integration Points (RIP)",
            "Value": "rip"
          },
          {
            "Label": "Third Party (Import API)",
            "Value": "third-party"
          }
        ],
        "Properties": {}
      }
    ],
    "States": [
      "complete",
      "complete-with-errors",
      "error",
      "canceled"
    ],
    "SelectableAsInitialTrigger": true
  },

  "Success": true,
  "Messages": [
    "Trigger v1/my-company/on-example-added-2 registered"
  ]
}

Delete a Trigger

Use this endpoint to delete a trigger from a workspace. A trigger will not be deleted if is part of a workflow, or part of an action within a workflow.

DELETE: {{host}}/Relativity.REST/api/relativity-automated-workflows/{versionNumber}/workspaces/{workspaceID}/triggers

JSON request

Copy 
{
    "triggerID": "relativity@example-trigger",
    "triggerVersion": 1
}

JSON response

Copy 
{
    "Success": true,
    "Message": "Trigger relativity@example-trigger with version 1 deleted"
}

List Actions

Use this endpoint to list actions. The JSON Request is empty for this call.

GET: {{host}}/Relativity.REST/api/relativity-automated-workflows/{versionNumber}/workspaces/{workspaceID}/actions

JSON response

Copy 
{
  "Result": [
    {
      "Label": "Email Example",
      "ID": "my-company/send-email",
      "Group": "Notifications",
      "Version": 1,
      "Inputs": [
        {
          "Label": "Recipient",
          "ID": "recipient-list-id",
          "Placeholder": "Enter email addresses separated by a semicolon (;)",
          "UIElementType": "Email"`
        }
      ],
      "Steps": [
        {
          "Type": "RPC",
          "Http": {
            "Url": "@{variables('RelativityInstanceURL')}/MyCompany.REST/API/v1/notification/workspace/@{variables('WorkspaceID')}/email/send",
            "Headers": {
              "x-csrf-header": "-",
              "content-type": "application/json"
            },
            "Body": {
              "body": {
                "WorkflowArtifactId": "@variables('WorkflowArtifactId')",
                "WorkflowRunId": "@workflow().run.id",
                "ActionDefinitionId": "@variables('ActionDefinitionId')",
                "ActionIndex": "@variables('ActionIndex')",
                "SequenceId": "@variables('SequenceId')"
              }
            },
            "Method": "Post"
          },
          "NotifiesCompletion": true
        }
      ]
    }
  ],
  "Success": true,
  "Messages": []
}

Create or Update an Action

Use this endpoint to create a new action or update an existing action.

PUT: {{host}}/Relativity.REST/api/relativity-automated-workflows/{versionNumber}/workspaces/{workspaceID}/actions

JSON request

Copy 
{
    "body": {
        "Label": "Send Email",
        "ID": "my-company/send-email",
        "Group": "Notifications",
        "Version": 1,
        "Inputs": [
            {
                "Label": "Recipient",
                "ID": "recipient-list-id",
                "Placeholder": "Enter email addresses separated by a semicolon (;)",
                "UIElementType": "Email"
            }
        ],
        "Steps": [
            {
                "Type": "RPC",
                "Http": {
                    "Url": "@{variables('RelativityInstanceURL')}/MyCompany.REST/API/v1/notification/workspace/@{variables('WorkspaceID')}/email/send",
                    "Headers": {
                        "x-csrf-header": "-",
                        "content-type": "application/json"
                    },
                    "Body": {
                        "body": {
                            "WorkflowArtifactId": "@variables('WorkflowArtifactId')",
                            "WorkflowRunId": "@workflow().run.id",
                            "ActionDefinitionId": "@variables('ActionDefinitionId')",
                            "ActionIndex": "@variables('ActionIndex')",
                            "SequenceId": "@variables('SequenceId')"
                        }
                    },
                    "Method": "Post"
                },
                "NotifiesCompletion": true
            }
        ]
    }
}

JSON response

Copy 
{
  "Result": {
    "Label": "Send Email",
    "ID": "my-company/send-email",
    "Group": "Notifications",
    "Version": 1,
    "Inputs": [
      {
        "Label": "Recipient",
        "ID": "recipient-list-id",
        "Placeholder": "Enter email addresses separated by a semicolon (;)",
        "UIElementType": "Email"
      }
    ],

    "Steps": [
      {
        "Type": "RPC",
        "Http": {
          "Url": "@{variables('RelativityInstanceURL')}/MyCompany.REST/API/v1/notification/workspace/@{variables('WorkspaceID')}/email/send",
          "Headers": {
            "x-csrf-header": "-",
            "content-type": "application/json"
          },
          "Body": {
            "body": {
              "WorkflowArtifactId": "@variables('WorkflowArtifactId')",
              "WorkflowRunId": "@workflow().run.id",
              "ActionDefinitionId": "@variables('ActionDefinitionId')",
              "ActionIndex": "@variables('ActionIndex')",
              "SequenceId": "@variables('SequenceId')"
            }
          },
          "Method": "Post"
        },
        "NotifiesCompletion": true
      }
    ]
  },
  "Success": false,
  "Messages": [
    "Already Registered in Workspace"
  ]
}

Create or Update an Action with Dynamic Rule

By default, all input fields are visible in the user interface. Dynamic Rules allow you to control this behavior by defining an expression that determines the visibility of an input field. In the action registration, the rule is defined for each input field that must be shown conditionally.

In order to add dynamic rules to an input field in your action, you will need to add a 'Properties' property to the payload, which will define the expression. For more information about the expression syntax, refer to Dynamic Rules Expression

Use this endpoint to create a new action or update an existing action with a dynamic rule.

PUT: {{host}}/Relativity.REST/api/relativity-automated-workflows/{versionNumber}/workspaces/{workspaceID}/actions

JSON request

Copy 
{
  "body": {
    "Label": "Set Long Text Field Size",
    "ID": "acme/set-long-text-field-size",
    "Group": "Document Update",
    "Version": 2,
    "Inputs": [
        {
            "Label": "All Documents",
            "ID": "set-field-on-all",
            "Placeholder": null,
            "DefaultValue": "true",
            "UIElementType": "Switch",
            "BooleanInputSource": {
                "TrueValue": "true",
                "FalseValue": "false",
                "TrueLabel": "Yes",
                "FalseLabel": "No"
            }
        },
        {
            "Label": "Saved Search",
            "ID": "saved-search-artifact-id",
            "Placeholder": "Select",
            "UIElementType": "Dropdown",
            "ObjectManagerQueryInputSource": {
                "LabelFieldName": "Name",
                "ValueFieldName": "ArtifactID",
                "Guid": "00000000-0000-0000-0000-000000000000",
                "ArtifactTypeID": 15
            },
            "Properties": {
                "VisibleExpression": "@action.inputs.set-field-on-all.value == 'false'"
            }
        }
    ],
    "Steps": [
        {
        "Type": "LongRunningRPC",
        "Http": {
            "Url": "@{variables('RelativityInstanceURL')}/Relativity.REST/api/setextractedtextsize/v1/sets/workspace/@{variables('WorkspaceID')}/StartSetsJob",
            "Headers": {
            "x-csrf-header": "-",
            "content-type": "application/json"
            },
            "Body": {
            "request": {
                "DatabaseToken": "AB8A1A95-24C1-4BB2-827E-ED70171711E1",
                "LongTextFieldArtifactId": "@{variables('long-text-field-artifact-id')}",
                "DecimalFieldArtifactId": "{@variables('decimal-field-artifact-id')}"
            }
            },
            "Method": "Post"
        },
        "StatusCheck": {
            "Http": {
            "Url": "@{variables('RelativityInstanceURL')}/Relativity.REST/api/setextractedtextsize/v1/sets/workspace/@{variables('WorkspaceID')}/GetJobProgress",
            "Headers": {
                "x-csrf-header": "-",
                "content-type": "application/json"
            },
            "Body": null,
            "Method": "Post"
            }
        },
        "Triggers": [
            {
                "Label": "Set Long Text Field Size Job Completed",
                "ID": "acme/set-long-text-field-size-completed",
                "SelectableAsInitialTrigger": true
            }
        ],
        "NotifiesCompletion": false
        }
    ]
  }
}

JSON response

Copy 
{
    "Success": true,
    "Message": "Action v2/acme/set-long-text-field-size registered",
    "Result": [
        "Action v2/acme/set-long-text-field-size created",
        "Trigger v2/acme/set-long-text-field-size-completed created"
    ]
}

Delete Action

Use this endpoint to delete an action from a workspace. An action will not be deleted if it is part of a workflow.

DELETE: {{host}}/Relativity.REST/api/relativity-automated-workflows/{versionNumber}/workspaces/{workspaceID}/actions

JSON request

Copy 
{
        "actionID": "my-company/example-action",
        "actionVersion": 1
}

JSON response

Copy 
{
    "Success": true,
    "Message": "Action my-company/example-action with version 1 deleted"
}

Send Trigger/Notify Event

Use this endpoint to send a trigger.

POST: {{host}}/Relativity.REST/api/relativity-automated-workflows/{versionNumber}/workspaces/{workspaceID}/notifiers/trigger

JSON request

Copy 
{
  "trigger": {
    "ID": "my-company/on-example-added",
    "Version": 1,
    "Message": "A Message",
    "State": "complete",
    "Inputs": [
      {
        "ID": "type",
        "Value": "processing"
      }
    ]
  }
}

JSON response

Copy 
{
  "Success": true,
  "Messages": [
    "Success or Failure Message indicating matching workflows"
  ]
}

Validate Workflow

Use this endpoint to determine if your workflow has any validation errors. The JSON Request is empty for this call.

POST: {{host}}/Relativity.REST/api/relativity-automated-workflows/{versionNumber}/workspaces/:workspaceID/workflow/:workflowID/validate

JSON response

// valid workflow

Copy 
{
    "Success": true,
    "Messages": []
}

// invalid workflow

Copy 
{
    "Success": false,
    "Messages": ["error message"]
}