API Documentation

  • Updated

InRule Process Automation supports integrations via API. This documentation describes how you can access the API to retrieve or update information in process applications that you have created.

Software and Protocol Requirements

There are no specific requirements, although support for the HTTP protocol and JSON data format is required in order to use the REST API.

API Version

1.0 - Current API version

1.1 – Update with some minor changes, only relevant to the following endpoints: https://live.barium.se/api/v1.1/domains/{SpaceId}/applicationmessages

https://live.barium.se/api/v1.1/domains/{SpaceId}/groups

https://live.barium.se/api/v1.1/domains/{SpaceId}/users

https://live.barium.se/api/v1.1/domains/{SpaceId}/usergroups

Base URL 

All API calls must start with a base URL. The base URL for Process Automation is https://live.barium.se/api/v1.x

Authentication, verification, and permissions

All API calls must contain a ticket in the header. The ticket is retrieved when authenticating the API username, password, and API key. Authentication is valid for 50 minutes on a sliding basis.

All API calls are based on the permissions that the API user holds. The permissions required are listed in the introduction of each endpoint category.

Global query strings

Format: JSON, XML – Sets the output format for the API call (Optional)

JSONP: {Method} - Enables JSON with padding which is useful in cross-site situations (Optional)

JSONText: True - Returns JSON with the content-type text/JSON instead of application/JSON (Optional)

Data Formats

  • All data except binary data is returned in JSON format by default.
  • All dates are returned in ISO-8601 format in coordinated universal time (UTC).
  • HTTP POST requests must include the HTTP Header "Content-Type"
    • For most requests, set to "application/x-www-form-urlencoded".
    • For file uploads, set to “multipart/form-data”.
  • HTTP POST parameters must be URL-encoded as "x-www-form-urlencoded" where non-ASCII characters must be encoded in UTF-8.
    • For file uploads, set as “multipart/form-data”
  • HTTP POST file uploads must conform to RFC 1867.

Error Messages

The backend will send given responses to certain endpoints.

Error messages are returned as standard HTTP error messages with an HTTP status code and a response in JSON format:

{success: false, errorCode: ERROR_CODE, errorMessage: “Error message”,
errorLogId: "ERROR_LOG_ID", errorData: ERROR_DATA}

ERROR_CODE is a standard HTTP status code (eg 400 = Bad request, 404 = Not found, 500 = Internal server error). At the times error messages are not generated, the protocol stack returns a status code itself that in rare cases is incorrect.

ERROR_LOG_ID refers to a logged error message that can contain more information about the error. The format of ERROR_DATA varies and depends on the error. An ERROR_LOG_ID is not always returned (errors on updating external value lists via API do send this, for example)

Dictionary

Parameters and descriptions

  • Resource - The type of resource you wish to access, e.g. process, instance, task, object
  • Id - The system-generated unique identifier or the registered unique identifier for the resource
  • Selector - Selects a specific set of data or underlying resource from the designated resource (Optional)
  • SelectorId - Selects an item from the specific set of data or the resource designated by the Selector (Optional)
  • SubSelector - Selects a specific set of data or underlying resource from the item specified by SelectorId (Optional)
  • SubSelectorId - Selects an item from the specific set of data or the resource designated by the SubSelector (Optional)
  • Domain – This is referred in the user interface as Space. Space Id is the four or five digit number in the URL string.
  • TypeNamespace – this is referred to in the user interface as Value list. Value list can be standard or extended. The URLs available for standard value lists contain “/Types/{TypeNamespace}”. The URLs available for extended value lists “domains/{SpaceId}/extendedvaluelists”. The permissons required to access the respective end points differ.

Set values

Assignable actions:

  • Complete a task
  • Assign a performer
  • Comment upon completing a task

Available status values on applications:

  • Running
  • Stopped

Available status values on instances:

  • Completed
  • Active
  • Ready
  • Cancelled
  • Aborted

Available status values on tasks:

  • Ready
  • Completed

Available status values on groups:

  • Added
  • Updated
  • Deleted

Fair usage policy

The API endpoints are available to all our customers free of charge.
Organizations should not use the API endpoints in a way that could damage or overburden the service. Organizations should not attempt to gain unauthorized access to data, accounts, or networks associated with InRule Process Automation.
If an organization makes excessive API calls, InRule Inc. reserves the right to restrict the integration's access to our APIs.

InRule Inc. requests that all developers consider and optimize their API calls to maintain optimal performance of our service, according to the “fair use” policy. InRule Inc. offers best-practice guidance on how to optimize API calls. Please contact the support team for assistance.

API Methods

InRule Process Automation’s REST API supports 5 types of requests:

GET

Requests information from Process Automation such as process models, forms, and files. This method also requests metadata for instances, tasks and objects.

POST

Submits data to Process Automation. This method is used for updating files and forms with information.

PUT

This method is for example used to update existing instance folders with new files.

PATCH

Works in the same way as PUT. The difference is that PATCH only updates partial parameters.

DELETE

This method is used to delete objects within Process Automation such as users, files, and instances.

API End points directory

Application messages

  • POST/domains/{SpaceId}/applicationmessages

Applications

  • GET/Apps
  • GET/Apps/{ApplicationId}
  • GET/Apps/{ApplicationId}/Instances
  • POST/Apps

Authenticate

  • GET/Authenticate
  • POST/Authenticate

Comments

  • GET /Instances/{InstanceId}/Comments
  • POST /Instances/{InstanceId}/Comments
  • DELETE /Instances/{InstanceId}/Comments/{CommentId}
  • GET /Instances/{InstanceId}/Objects/{ObjectId}/Comments
  • POST /Instances/{InstanceId}/Objects/{ObjectId}/Comments
  • DELETE /Instances/{InstanceId}/Comments/{CommentId}

Form templates

  • GET /DataFormTemplates
  • GET /DataFormTemplates/{DataFormTemplateId}
  • GET /DataFormTemplates/{DataFormTemplateId}/Fields
  • GET /DataFormTemplates/{DataFormTemplateId}/Definition

Instances

  • GET /Instances
  • GET /Instances/{InstanceId}
  • GET /Instances/{InstanceId}/Objects
  • GET /Instances/{InstanceId}/Objects/{ObjectId}
  • GET /Instances/{InstanceId}/Tasks
  • GET /Instances/{InstanceId}/Tasks/{TaskId}
  • POST /Instances/{InstanceId}/Objects
  • POST /Instances/{InstanceId}
  • POST /DataForms/{DataFormId}/Attachments
  • DELETE /Instances/{InstanceId}

Lists

  • GET /v1.0/lists
  • GET /v1.0/lists/{ListId}
  • GET /v1.0/lists/{ListId}/data
  • GET /v1.0/lists/{ListId}/count

Objects

  • GET /Objects/{ObjectId}
  • GET /Objects/{ObjectId}/Objects
  • GET /Objects/{ObjectId}/Fields
  • GET /Objects/{ObjectId}/PDF
  • GET /Objects/{ObjectId}/Image
  • GET /Objects/{ObjectId}/File
  • POST /Objects/{ObjectId}/Objects
  • POST /Objects/{ObjectId}/Fields
  • PUT /Objects/{ObjectId}
  • PUT /Objects/{ObjectId}/Objects/{ReferenceId}
  • POST /Objects/{ObjectId}
  • POST /Objects/{ObjectId}/Objects/{ReferenceId}
  • DELETE /Objects/{ObjectId}
  • DELETE /Objects/{ObjectId}/Objects/{ReferenceId}

Processes

  • GET /Processes
  • GET /Processes/{ProcessId}

Spaces

  • GET /Domains/{SpaceId}/Processes
  • GET /Domains/{SpaceId}/Apps
  • GET /Domains/{SpaceId}/Startevents
  • GET /Domains/{SpaceId}/Instances
  • GET /Domains/{SpaceId}/Tasks
  • GET /Domains/{SpaceId}/InstanceObjects
  • GET /Domains/{SpaceId}/InstanceObjectsFields
  • GET /Domains/{SpaceId}/DataFormTemplates
  • GET /Domains/{SpaceId}/DataFormTemplatesFields

Start events

  • GET /startevents
  • GET /startevents/{StarteventId}
  • GET /startevents/{StarteventId}/assignableparticipants
  • GET /startevents/{StarteventId}/assignableparticipants/{ParticipantId}
  • GET /startevents/{StarteventId}/DataFormTemplates
  • GET/startevents/{StarteventId}/DataFormTemplates/{DataFormTemplateId}/fields
  • POST /startevents/{StarteventId}

Tasks and Actions

  • GET /Tasks
  • GET /Tasks/{TaskId}
  • GET /Tasks/{TaskId}/Objects
  • GET /Tasks/{TaskId}/Objects/{ObjectId}
  • GET /Tasks/{TaskId}/Objects/{ObjectId}/Fields
  • GET /Tasks/{TaskId}/References
  • GET /Tasks/{TaskId}/References/{ReferenceId}
  • GET /Tasks/{TaskId}/Actions
  • GET/ Tasks/{TaskId}/Actions/{ActionId}/AssignableParticipants
  • GET/ Tasks/{TaskId}/Actions/{ActionId}/AssignableParticipants/{ParticipantId}
  • POST/Tasks/{TaskId}/Actions/{ActionId}
  • POST/ Tasks/{TaskId}/Actions/{ActionId}?participants[{participant:’Id’,securityIds:’Identifier}]

Users and Groups

  • GET /domains/{SpaceId}/users
  • GET /domains/{SpaceId}/usergroups
  • GET /domains/{SpaceId}/groups
  • POST /domains/{SpaceId}/users
  • POST /domains/{SpaceId}/disableusers
  • POST /domains/{SpaceId}/groups
  • DELETE /domains/{SpaceId}/groups

Value lists

  • GET /Types
  • GET /Types/{TypeNamespace}
  • GET /Types/{TypeNamespace}/TypeInstances
  • GET /domains/{SpaceId}/extendedvaluelists
  • GET /domains/{SpaceId}/extendedvaluelists/{ExtendedvaluelistId}
  • PATCH domains/{SpaceId}/extendedvaluelists/{ExtendedvaluelistId}

Create your first API application using Postman

This article will guide you through the steps for creating your first API application using Postman.

Download Postman and install it on your computer. The Postman Collection in this article will do the following:

  1. Log into InRule Process Automation with the API user’s credentials.
  2. Extract the login ticket for subsequent API calls.
  3. Search through the applications for which it has permissions, for an application called: API-Application, and get the Id. (The process name is the one set by you in Process Automation.)
  4. Start an instance with the collected Id with data specified in the collection variables.
  5. When the instance is started, the Postman collection verifies the values in the form for the created instances.

Instructions for creating API application

  1. Create an application in Process Automation.
  2. Make sure that there is a form with at least two fields, it can be configured in the following way: 
    blobid0.png

  3. Associate the form with the start event, and configure the start event message to be able to perform the API calls correctly:
    blobid1.png

    blobid2.png

    blobid3.png

  4. Deploy the application in Process Automation.
  5. Download the postman collection here.

    This article is written for Postman version v9.15.2, other versions of Postman may not be compatible with this collection.

  6. Open Postman and click  Import , then choose the provided file for the collection.
    blobid4.png

  7. Navigate to the Variables tab and  fill in the values that correspond to your credentials. The API key is found in the Space Settings in Process Automation.
    blobid5.png

  8.  Run the collection in Postman. The expected result is a new instance is created with your data in the form.

Authenticate

When to use Authentication

Authentication normally takes place every time an API call is initiated. Authentication is valid for 50 minutes on a sliding basis. This means that each successful call extends authentication. If you are making successive calls, it is only required to authenticate initially. This endpoint is cached for 15 seconds. If you make the exact same call within these 15 seconds, you will receive cached data.

Examples:

  • Authenticate to retrieve a list
  • Authenticate to start an instance

Syntax:

  • GET/Authenticate
  • POST/Authenticate

Header:

  • N/A

Test authentication

Displays a login form allowing browser-based authentication for test purposes. An API key, a username, and a password must be specified to authenticate against the API.

Verb: Get

Header: No

Query parameters available: N/A

Returns:

Web page allowing a user to authenticate against the API using a standard web browser.

Authentication

https://live.barium.se/api/v1.0/Authenticate  

Post login details to authenticate the user.

Authenticate the user using an API key, a user name and a password.

Set the query string parameter format=json to get a JSON-formatted response when authenticating.

If authenticating with format=json, the return JSON format will be: { success=true, Ticket="TICKET" }

Verb: Post

Header: No

Query parameters required:

  • APIKey
  • Username
  • Password

Returns:

Ticket

Example request

POST https://live.barium.se/api/v1.0/authenticate

Content-type: application/x-www-form-urlencoded

username=someuser@bariumlive.se&password=ABC123&apikey=f166af40-aa84-4cda-83f4-3f60c2298cc4&webTicket=true

The answer on this example call is:

{
“success” : true,
“ticket” : (string),
“WebTicket” : (string)
}

It is the value in the ticket that needs to be used in following calls by sending the value as a header with the name ticket

Application messages

When to use application messages

This method is used when you want to let Process Automation make information available to another system.

Examples:

  • Information can be collected when suitable
  • Information is required to be collected at a point in the process rather than a point in time

Syntax:

  • POST /domains/{SpaceId}/applicationmessages

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/json

API user will only fetch the queues for which it has been given permissions. To set permissions, navigate to user management and grant the API user “Admin” permissions.

Retrieve application messages

https://live.barium.se/api/v1.1/domains/{SpaceId}/applicationmessages  

The API call is used to fetch data from a queue.

When a message is retrieved it is marked as processed and will not be returned again.

Max 100 messages returned in the response. If the data returned is 100 rows, you must do another call to retrieve the remaining data. As soon as you receive zero rows in your result there is no need to call again.

Verb: Post

Query parameters available: N/A

Post data:

{
"queueName": "00000000-0000-0000-0000-000000000001.queue-name"
}

Returns:

Array of messages with properties

  • Id - "id"
  • Queue name - "queueName"
  • Message (array) - "message"
  • Created date - "createdDate"
  • Is processed - "isProcessed"
  • Processed date - "processedDate"
  • Processed by security Id - "processedBySecurityId"
  • Space object Id - "spaceObjectId"

To use the Application messages endpoint you need to call for API/v1.1 in the URL.

Example request:

POST: https://live.barium.se/API/v1.1/domains/1234/applicationmessages
Header ticket=yourticket
POST data:
{
"queueName": "00000000-0000-0000-0000-000000000001.queue-name"
}

The queue name can be found in Process Studio when Configuring a message.
Here you can find a tutorial on how to set up an application message.

Applications

When to use Applications

Get process application information from process applications.

Examples:

  • See which applications the API user has access to
  • Find out if an application is active or paused
  • Retrieve instances in an application
  • Start an instance

Syntax:

  • GET/Apps
  • GET/Apps/{ApplicationId}
  • GET/Apps/{ApplicationId}/Instances
  • POST/Apps/{ApplicationId}

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded

The API user will only access the information for which it has been given permission. To set permissions, navigate to the process model for the process application and give the API user access to see and edit instances. To give it access to start instances, the API user needs to be associated to the lane in which the start event lies.

List available applications

https://live.barium.se/api/v1.0/Apps 

Lists the applications that the API user has access to.

Verb: Get

Query parameters available:

Start (int)

Max (int)

Returns:

Total application count

Data (array):

  • Application Id
  • Name
  • Description
  • Status of application
  • Instances count

Get metadata for a process application

https://live.barium.se/api/v1.0/Apps/{AppId}  

Fetches information regarding a specific application, for example, its name or number of instances.

Verb: Get

Query parameters available:

N/A

Returns:

Object:

  • Application Id
  • Name of the application
  • Description
  • Status of application
  • Instances count

List instances

https://live.barium.se/api/v1.0/Apps/{ApplicationId}/Instances  

List available instances in a process application. Filter the instances based on status, available values can be found in the introduction. Calls return the first 50 instances, therefore pagination may be necessary.

Verb: Get

Query parameters available:

Start (int)

Max (int)

Status (string)

Returns:

Total count of instances

Data (array):

  • Instance Id
  • Name of instance
  • Description
  • Status of instance
  • Start date
  • Started by

Start a new instance

https://live.barium.se/api/v1.0/Apps/{ApplicationId}

Or

https://live.barium.se/api/v1.0/Apps/{ApplicationId}?message={messageRefName}/

The first call triggers a specific start event to create a new instance in a process application. The second call enables the API user to send a named message to a process application, which triggers a start event of type catching message. The message must be named by adding a message parameter (default message name is "START"). The message name corresponds to a Message Start Event with a property called MessageRefName. There are examples of both calls.

Information about starting an instance from a message start event with data:

Form data may be included in the message start event. If form data is sent, the form template associated with the start event in the process model cannot be empty. The form template has a unique identifier, called data object Id.

Include the HTTP Header "Content-Type" set to "application/x-www-form-urlencoded". Form data sent as HTTP POST parameters are uniquely named. Add all parameters to the request body on the following format (URL-encoded): parameter1=value1, parameter2=value2 etc.

Field names and values are separated by an ampersand character &: field1=201-1101&field2=InRule+AB, where “field1” is the name of the form field and “201-1101” is the value.

it is not possible to add files to start events with data.

Verb: Post

Query parameters available:

Message (string)

Template (string)

         Data object Id (string)

Returns:

Object:

Success status
Instance Id

Example request, starting an instance from a message start event without form data:

Send a POST with the content-type: application/x-www-form-urlencoded and the header: ticket=[ticket from the authentication] to the following url: https://live.barium.se/api/v1.0/apps/{APP-ID}?message={MESSAGE}

  • A ticket 
  • The application Id 
  • The message name for the start event you wish to activate
  • The field names for the fields that will receive information for the start

POST 

https://live.barium.se/api/v1.0/apps/49f32323-d79e-4a0f-bb4c-d5fc16bb4340

Headers

  • ticket=f1327af40-aa84-4cda-83f4-3f60c2298cc4
  • Content-type=application/x-www-form-urlencoded

Data

  • message=START

The answer to this example call is:

{
“success” : true,
“InstanceId” : (string)
}

Success : true means that the instance was created successfully and the InstanceId is this instance unique identifier.

Example request, starting an instance from a message start event with data:

template={form}&message={START}&field1=201-1101&field2=InRule+AB

How to send a request that initiates an instance with form data:

  1. Configure the type of the start event to a message start event and open the Configure message dialog to set the message reference name.
    blobid4.png

  2. Connect the form to the start event.
    blobid5.png

  3. Add fields to the form.
    blobid6.png


  4. Connect the form fields to the configured message in the start event. Open the message configuration panel and specify which names the message parameters have and connect them to the form field names.

    blobid7.png

  5. Invoke the start event via the API by: 
POST https://live.barium.se/api/v1.0/apps/{49f32323-d79e-4a0f-bb4c-d5fc16bb4340}?message={START}

Content-Type: application/x-www-form-urlencoded

template={Form}&message={START}&field1=201-1101&field2=InRule+AB

If form data is sent when starting an instance, the parameter template cannot be empty. The template, most commonly, is the data form object ID is used. If you wish to only start an instance, leave template empty and leave the fields undefined.

Comments

When to use Comments

This set of API calls manipulates the comments functionality in Process Automation.

Examples:

  • Create or delete comments against tasks or instances
  • List all comments or get a specific comment against a task or instance

Syntax:

  • GET /Instances/{InstanceId}/Comments
  • GET /Instances/{InstanceId}/Comments/{CommentId}
  • GET /Instances/{InstanceId}/Objects/{ObjectId}/Comments
  • GET /Instances/{InstanceId}/Objects/{ObjectId}/Comments/{CommentId}
  • POST /Instances/{InstanceId}/Comments
  • POST /Instances/{InstanceId}/Comments/{CommentId}
  • POST /Instances/{InstanceId}/Objects/{ObjectId}/Comments
  • DELETE /Instances/{InstanceId}/Comments/{CommentId}
  • DELETE /Instances/{InstanceId}/Objects/{ObjectId}/Comments/{CommentId}

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded

The API user will only have access to the comments for which it has been given permission. To set permissions, navigate to the process model for the process application and give the API user access to see and edit instances.

List all comments for an instance

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Comments

This call lists all comments and their respective replies for an instance.

Verb: Get

Query parameters available:

pageIndex (int)

pageSize (int)

Returns:

Total records

Page index

Page size

Comments (Array)

          Comment result

 

Get a specific comment

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Comments/{CommentId}

This call retrieves a specific comment and its respective replies.

Verb: Get

Query parameters available: N/A

Returns:

Comment Id

Author security Id

Author name

Child comments (Array)

           Comment result

Created date

Edited date

Text

Is viewed

Object Id

Object name

Object Type

Parent comment Id

Get all comments or a specific comment for an instance object (e.g. documents)

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Objects/{ObjectId}/Comments

Comments are most commonly documented at instance level, but it is also possible to configure comments to instance objects such as documents.

Verb: Get

Parameters available:

pageIndex (int)

pageSize (int)

Returns:

Total records

Page index

Page size

Comments (Array)

        Comment result

Get a specific comment for an instance object

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Objects/{ObjectId}/Comments/{CommentId}

Comments are most commonly documented at instance level, but it is also possible to configure comments to instance objects such as documents.

Verb: Get

Query parameters available: N/A

Returns:

Comment Id

Author security Id

Author name

Child comments (Array)

           Comment result

Created date

Edited date

Text

Is viewed

Object Id

Object name

Object type

Parent comment Id

Create a new comment or reply to another comment in an instance

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Comments

or

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Comments/{CommentId}

This call creates a new comment or a new reply. If the intention is to post a new comment, do not use the parameter parentCommentId. If the intention is to post a reply to a comment, please use parentCommentId.

Verb: Post

Query parameters available:

text (string)

parentCommentId (string)

Returns:

Comment Id

Author security Id

Author name

Child comments (Array)

           Comment result

Created date

Edited date

Text

Is viewed

Object Id

Object name

Object type

Parent comment Id

Create a comment for an instance object

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Objects/{ObjectId}/Comments

Comments are most commonly documented at instance level, but it is also possible to configure comments to instance objects such as documents.

Verb: Post

Query parameters available:

text (string)

parentCommentId (string)

Returns:

Comment Id

Author security Id

Author name

Child comments (Array)

             Comment result

Created date

Edited date

Text

Is viewed

Object Id

Object name

Object type

Parent comment Id

Delete a comment

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Comments/{CommentsId}

This call deletes a comment. It cannot delete a reply.

Verb: Delete

Query parameters available: N/A

Returns: An HttpStatusCode will be returned.

Delete a specific comment for an instance object

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Objects/{ObjectId}/Comments/{CommentId}

Comments are most commonly documented at instance level, but it is also possible to configure comments to instance objects such as documents.

Verb: Delete

Query parameters available: N/A

Returns: An HttpStatusCode will be returned.

Form templates

When to use Form Templates

Form templates constitute a data model, therefore their endpoints are called DataFormTemplates. These are used to define which data to capture in the process. There is a separate set of endpoints for updating data within instantiated forms, please read the Instances section.

Examples:

  • Get all the form templates that the API user has access to
  • Get metadata for a form template to understand when it was last updated
  • Get all the fields in a form template

Syntax:

  • GET /DataFormTemplates
  • GET /DataFormTemplates/{DataFormTemplateId}
  • GET /DataFormTemplates/{DataFormTemplateId}/Fields
  • GET /DataFormTemplates/{DataFormTemplateId}/Definition

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded

The API user will only access the information for which it has been given permission. To set permissions, navigate to the process model for the process application and give the API user access to see and edit instances.

List available form templates

https://live.barium.se/api/v1.0/DataFormTemplates

Lists the form templates available to the API user. These may be used to create new instantiations of forms.

Verb: Get

Query parameters available:

Start (int)

Max (int)

Returns:

Total count

Data (array)

  • Form template Id
  • Reference Id
  • Object class
  • Name of form template
  • Description
  • Created date
  • Changed date

Get metadata for a form template

https://live.barium.se/api/v1.0/DataFormTemplates/{TemplateId}

Get the meta data captured against a specific form template

Verb: Get

Query parameters available:

VersionId (string)

Returns:

Object:

  • Form template Id
  • Reference Id
  • Object class
  • Name of form
  • Description
  • Field TypeNamespace (Value list Id, will only be populated if the field is a value list)
  • Created date
  • Changed date

List all fields in a form template

https://live.barium.se/api/v1.0/DataFormTemplates/{TemplateId}/Fields

This call retrieves the first 200 fields in a form template. If the form template contains more than 200 fields, pagination is necessary.

Verb: Get

Query parameters available:

VersionId (string)

Start (int)

Max (int)

Returns:

Fields (Array)

  • Field Id
  • Name of field
  • Data type
  • Field type
  • Field TypeNamespace (Value list Id, will only be populated if the field is a value list)
  • Read only
  • Index

Example request:

Receive 4500 form fields

Call 1: max = 2000, start = 0           Receive the first 2000 first items.

Call 2: max = 2000, start = 2000  Receive items 2001 to 4000.

Call 3: max = 2000, start = 4000   Receive items 4001 to 4500. If you receive less than 2000 items back, then you know that there are no more items to ask for.

 Get the template definition

https://live.barium.se/api/v1.0/DataFormTemplates/{TemplateId}/Definition

If you need the whole template definition in JSON, it is possible to retrieve it as an object.

Verb: Get

Query parameters available: N/A

Returns:

Object:

  • Form definition
  • Is HTML form
  • Stylesheet
  • JavaScript

Stylesheet and JavaScript are only populated if the form is an HTML form. Most forms are not HTML forms.

Instances

When to use instances

This set of endpoints enables organizations to programmatically update instances and objects within instances. In order for the calls to be successful, the API user needs permission to edit instances. This is granted in the permissions settings in Process Studio.

Examples:

  • Get all the instances and their status in a process application
  • Get or update the form in an instance
  • Get all tasks in an instance
  • Get specific fields from a form
  • Delete an instance

Syntax:

  • GET /Instances
  • GET /Instances/{InstanceId}
  • GET /Instances/{InstanceId}/Objects
  • GET /Instances/{InstanceId}/Objects/{ObjectId}
  • GET /Instances/{InstanceId}/Tasks
  • GET /Instances/{InstanceId}/Tasks/{TaskId}
  • POST/Instances/{InstanceId}/Formfields
  • POST /Instances/{InstanceId}/Objects
  • POST /Instances/{InstanceId}
  • DELETE /Instances/{InstanceId}

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded
  • Content-Type for adding a file to an instance: multipart/form-data

the API user will only access the instances for which it has been given permissions. To set permissions, navigate to the process model for the process application and give the API user access to see and edit instances.

Get all instances

https://live.barium.se/api/v1.0/Instances

This query gets all the instances that the API user has access to. This may include multiple applications. It is possible to filter instances by status. Available status values can be found in the introduction.

If no instances are available, an empty array is returned.

Verb: Get

Query parameters available:

Status (string)

Start (int)

Max (int)

Returns:

Total count

Data (array)

  • Instance Id
  • Name of instance
  • Description
  • Status of instance
  • Milestone
  • Start date
  • Started by
  • Completed date
  • Application name

Get data for an instance

https://live.barium.se/api/v1.0/Instances/{InstanceId}

This will retrieve the metadata for a specific instance. This endpoint is useful for fetching the form Id, which in turn can be used to fetch form fields.

Verb: Get

Query parameters available: N/A

Returns:

Object

  • Instance Id
  • Name of instance
  • Description
  • Status of instance
  • Milestone
  • Start date
  • Started by
  • Started by user Id
  • Completed date
  • Priority
  • Planned date
  • Deadline date
  • Application Id
  • Application name
  • Parent instance name
  • Parent instance Id

List all objects in an instance

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Objects

This call returns a list of objects housed in an instance. For example: files, folders, or forms.

Verb: Get

Query parameters available:

Start (int)

Max (int)

Returns:

Total count

Data (array):

  • Object Id
  • Name of object
  • Description
  • Object class
  • Container
  • File type

Get data for an object in an instance

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Objects/{ObjectId}

This call returns the meta data of objects housed in an instance. This endpoint should be used for most operations on objects in instances.

Verb: Get

Query parameters available:

VersionId (string)

Returns:

Object:

  • Object Id
  • Name of object
  • Description
  • Object class
  • Container
  • File type

Example request:

https://live.barium.se/api/v1.0/instances/aaaaaaaa-a9d6-419e-bc7f-4ad7b61dc8d3/objects
Method: GET
Headers: "ticket", {ticket}
Body: none

Response:
{
   "TotalCount": 1, 
   "Data": [ 
       { 
           "Id": " aaaaaaaa-0baf-4bd3-bc23-7eabfc8af6ad", 
           "ReferenceId": null, 
           "Name": "form", 
           "Description": "", 
           "Type": "dataform", 
           "ObjectClass": "dataforms.dataform", 
           "Container": false, 
           "ReadOnly": false, 
           "TypeNamespace": null, 
           "TemplateId": " aaaaaaaa-5561-4043-9c1a-1a70d97b79cf", 
           "FileType": "", 
           "SortIndex": null, 
           "State": null, 
           "CreatedDate": "2022-09-23T11:28:29Z", 
           "UpdatedDate": "2022-09-23T11:28:29Z", 
           "DataId": "form" 
       } 
   ] 
}

List available tasks

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Tasks

This lists all available tasks in an instance. If no tasks are available, an empty array is returned. The max amount the api user is permitted to get is 50.

Verb: Get

Parameters available:

Start (int)

Max (int)

Status (string)

Returns:

Total count

Data (array)

  • Task Id
  • Name of task
  • Description
  • Task status
  • Created date
  • Completed date
  • Completed by
  • Instance name
  • Application name
  • Participants
  • Locked
  • Perform permission

Get data for a task in an instance

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Tasks/{TaskId}

Gets metadata for a task in an instance.

Verb: Get

Parameters available: N/A

Returns:

Object

  • Task Id
  • Name of task
  • Description
  • Task status
  • Created date
  • Completed date
  • Completed by
  • Completed by user Id
  • Instance name
  • Instance Id
  • Application name
  • Application Id
  • Locked
  • Perform permission

Get specific fields from a form

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Formfields

Gets data from specific form fields. The request contains a body with the specified data points, using the form name and the field name. See example below, where the form is named "form" and the field name "Field1", "multiSelect" and "extendedList" respectively. 

Lists may contain two values - display value and value. The display value will only be listed if there is one.

Verb: Post

Example Request

Content-Type: application/json

[
    "form.Field1",
    "form.multiSelect",
    "form.extendedList"
]

Example Response

[
    {
        "Input": "form.Field1",
        "Value": "Ipsum lorem",
    },
    {
        "Input": "form.multiSelect",
        "Value": "no, unsure",
        "DisplayValue": "No, unsure"
    },
    {
        "Input": "form.extendedList",
        "Value": "2",
        "DisplayValue": "Sweden"
    }
]

Add objects to an instance

https://live.barium.se/api/v1.0/Instances/{InstanceId}/Objects

Adds/uploads a file, folder or form to an instance folder (to the root folder of the instance).

Verb: Post

Query parameters available:

Type (string)

Name (string)

TemplateId (string)

Fields (array)

            (Data (object/binary))

Returns:

Object:

        Success

        Id

Send a message to an instance

https://live.barium.se/api/v1.0/Instances/{InstanceId}

Sends a named message to a process instance to trigger an intermediate event. The message must be named by using the message parameter. The success return value will return True if the message was sent successfully.

If you want to post to a boundary intermediate event you must add the message parameter as a query string with your POST (e.g. /Instances/{InstanceId}?message={Message}).

Catching intermediate messages cannot receive Data.

Verb: Post

Query parameters available:

Message (string)

Returns:

Success status

Delete an instance

https://live.barium.se/api/v1.0/Instances/{InstanceId}

Deletes an existing instance by sending a delete call to an existing resource URL. If an instance is deleted all objects within the instance will also be deleted, such as typed objects, files and folders. It is currently not possible to delete multiple instances at the same time.

Verb: Delete

Query parameters available: N/A

Returns:

Success status

Attaching files to forms

It is possible to upload one or more attachments to a form that has been created in an active instance.

Example:

  • Add a signed contract to an onboarding form
  • Add one or more pictures to a form

Syntax:

  • POST /DataForms/{DataFormId}/Attachments

Header:

  • Ticket previously generated from authentication
  • Content-Type: multipart/form-data

The API user will only attach files to forms for which it has been given permission. To set permissions, there are three options:

  1. Navigate to the process model for the process application and give the API user access to see and edit instances through Process settings.
  2. Navigate to the process model for the process application and add the API user to the lane in which the task is performed. This is done by deploying the application.
  3. Manually assign the task to the API user.

Upload one or more files to the attachment fields in a form

https://live.barium.se/api/v1.1/DataForms/{DataFormId}/Attachments

Files are automatically uploaded to the form object if the client sends an HTTP POST with the Content-Type header of the request set to multipart/form-data

The name must be the same as the attachment fields’ IDs in order for the file(s) to be uploaded.

Empty files cannot be uploaded.

In the response, there is an ignored fields object which contains fields that did not match any existing field in the form. This may be because the field does not exist, or because the type is not configured as an attachment field.

Verb: Post

Query parameters available: N/A

Returns:

Object:

  • Success status
  • Updated fields
  • Ignored fields

Example request:

Content-Disposition: form-data; name="AttachmentField1"; filename="file.txt"

Lists

When to use Lists

This set of endpoints enables organizations to fetch information from lists.

Examples:

  • Get all the objects in a list, and the information captured in the included columns
  • Get the total count of objects in a list

Syntax:

  • GET /v1.0/lists
  • GET /v1.0/lists/{ListId}
  • GET /v1.0/lists/{ListId}/data
  • GET /v1.0/lists/{ListId}/count

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded

The API user will only access the information for which it has been given permission.

For lists, it is required that the API user is given permission to view the list and permissions to see the contents in the list such as instances and tasks. 

To set permissions to view the list

Navigate to the list configuration and give the API user access.

To set permissions to view instances

Navigate to the process model for the process application and give the API user access to see and edit instances through Process settings.

To set permissions to view tasks

This can be done in two ways:

  • Navigate to the process model for the process application and add the API user to the lane in which the task is performed. This is done through deploying the application.
  • Or, manually assign tasks to the API user.

List all lists

https://live.barium.se/api/v1.0/lists

Get all the lists the API user has access to.

Verb: Get

Query parameters available: N/A

Returns:

Access type

Created date

Created by

List Id

Name of list

Type

Get the columns in a list

https://live.barium.se/api/v1.0/lists/{ListId}

Get information about what columns are configured in a list.

Verb: Get

Query parameters available: N/A

Returns:

List Id

Name of list

Created date

Type

Created by

Access type

Column data (Array)

  • Data index
  • Name of column
  • Data type
  • Hidden
  • Sortable

Example response:

[
    {
        "id": "8a42260c-04d1-42ae-909f-aaaaaaaaaaaa",
        "name": "Test list",
        "type": "Instances",
        "created": "2022-02-15T13:29:38Z",
        "createdBy": "Firstname Lastname (username@barium.se)",
        "accessType": 1,
        "columns": [
            {
               "dataindex": "0",
               "name": "Instance_ObjectID",
               "datatype": "string",
               "hidden": false,
               "sortable": true,
               "heading": "Instance ID"
            },
            {
               "dataindex": "1",
               "name": "Instance_Name",
               "datatype": "string",
               "hidden": false,
               "sortable": true,
               "heading": "Instance"
            },
            {
                "dataindex": "2",
                "name": "form.response",
                "datatype": "string",
                "hidden": false,
                "sortable": true,
                "heading": "FieldLabel"
            }
        ]
    }
]

Get a list and its contents

https://live.barium.se/api/v1.0/lists/{ListId}/data

Get the items in a list and their corresponding columns. The maximum amount of list items per call is 2000. If more are needed, paginate using query parameter “?skip=0&take=100”. If the returned result is not an empty array, increase the skip parameter by 100. The request then becomes “?skip=100&take100”. Keep increasing the skip parameter until the response contains an empty array.

Verb: Get

Query parameters available:

skip (int)

take (int)

sortkey (string)

sortdir (string)

filter (string)

fromCreatedDate (datetime)

toCreatedDate (datetime)

fromActivityDate (datetime)

toActivityDate (datetime)

fromActivityDate and toActivityDate are only applicable for lists type "Instance".

Returns:

An array of objects where its properties correspond with the column's data index and where "value" is the value for that particular cell.

Example request with a list containing standard columns, as well as two columns from a form. The list contains two instances:

https://live.barium.se/api/v1.0/lists/aaaaaaaa-a4d1-42ae-909f-dd78393d01d9/data

Method: GET

Header: "ticket", {ticket}

Body: none

Example response from lists/data:

[
   {
       "Instance_ChildInstanceCount": 0,
       "Instance_ParentObjectID": null,
       "Instance_RootInstanceObjectACLID": 11111111,
       "Instance_ACLID": 11111111,
       "Instance_ObjectID": "8faa65d4-8c9d-479e-918f-586aaaaaaaaa",
       "form.field1" : "InRule AB",
       "form.field2": "11-201"
},
{
       "Instance_ChildInstanceCount": 0,
       "Instance_ParentObjectID": null,
       "Instance_RootInstanceObjectACLID": 22222222,
       "Instance_ACLID": 22222222,
       "Instance_ObjectID": "b289df41-c168-4d39-95c9-c8baaaaaaaaa",
       "form.field1" : "InRule AB",
       "form.field2": "11-201"
    }
]

Get the item count for a list

https://live.barium.se/api/v1.0/lists/{ListId}/count

Get a count of the number of items in a list.

Verb: Get

Query parameters available:

filter (string)

fromCreatedDate (datetime)

toCreatedDate (datetime)

fromActivityDate (datetime)

toActivityDate (datetime)

fromActivityDate and toActivityDate is only applicable for lists of type “Instance”

Returns:

Total count

Objects

When to use Objects

This set of endpoints enables organizations to configure objects contained in instances. The API user must have permission to the instance in order to configure the objects.

Examples:

  • Get information for an object
  • Create new objects or delete existing objects
  • Update data in objects

Syntax:

  • GET /Objects/{ObjectId}
  • GET /Objects/{ObjectId}/Objects
  • GET /Objects/{ObjectId}/Fields
  • GET /Objects/{ObjectId}/PDF
  • GET /Objects/{ObjectId}/Image
  • GET /Objects/{ObjectId}/File
  • POST /Content-Type/Objects/{ObjectId}/Objects
  • POST /Objects/{ObjectId}/Objects
  • POST /Objects/{ObjectId}/Fields
  • PUT /Objects/{ObjectId}
  • PUT /Objects/{ObjectId}/Objects/{ReferenceId}
  • POST /Objects/{ObjectId}
  • POST /Objects/{ObjectId}/Objects/{ReferenceId}
  • DELETE /Objects/{ObjectId}
  • DELETE /Objects/{ObjectId}/Objects/{ReferenceId}

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded
  • Content-Type for adding a file to an object: multipart/form-data

The API user will only access the object that it has been given permission to.

To set permissions to view objects in instances

Navigate to the process model for the process application and give the API user access to see and edit instances.

To set permissions to view objects in tasks

This can be done in two ways:

  • Navigate to the process model for the process application and add the API user to the lane in which the task is performed. This is done by deploying the application.
  • Or, manually assign the task to the API user.

Get information for an object

https://live.barium.se/api/v1.0/Objects/{ObjectId}

Get metadata for an object, for example, a form or a file.

Verb: Get

Query parameters available:

VersionId (string)

Returns:

Object Id
Parent Id
Reference Id
Name of object
Description
Object class
Type
Container (Array)
Read only
TypeNamespace (Value list Id, will only be populated if the field is a value list)
Template Id
File type
Sort index
State of the object
Data Id

List items in a folder

https://live.barium.se/api/v1.0/Objects/{ObjectId}/Objects

Lists available items in a container object (such as a folder)

Verb: Get

Query parameters available:

VersionId (string)

Start (int)

Max (int)

Returns:

Total count

Data (Array)

  • Object Id
  • Name of object
  • Description
  • Object class
  • Container
  • File Type

List all fields in a form

https://live.barium.se/api/v1.0/Objects/{ObjectId}/Fields

Lists all fields in an object, such as all fields for a form. Data is returned in pages. Default number of fields fetched is 200.

Returned total count is not correct. Data can be stored on the next page even if received rows in data are less than the page size.
Recommendations:
- Make sure to use parameters Start and Max with a page size (Max) of e.g. 200
- Make calls until the number of rows in the Data section is 0.

Data from this endpoint needs to be fetched in a special way. Field types (Type) that can be returned are:

  • Check box
  • Date field
  • File upload field (attachment field)
  • Html editor (text area input field with HTML editor)
  • Number field
  • Radio button
  • Text area (multi-line)
  • Text field (single line)
  • Time field
  • Select (single value drop-down box)
  • Multi-select (multi value drop-down box)

Verb: Get

Query parameters available:

VersionId (string)

Start (int)

Max (int)

Returns:

Object (Array)

  • Object Id
  • Name of object
  • Data type
  • Field type
  • Value
  • Field TypeNamespace (Value list Id, will only be populated if the field is a value list)
  • Read only
  • Index

Example request:

Call 1:

/Objects/{ObjectId}/Fields?start=0&max=200

The number of rows in Data-section might be 170. Make a new call with increased Start value.

Call 2:

 /Objects/{ObjectId}/Fields?start=200&max=200

The number of rows in Data-section might be 20. Make a new call with increased Start value.

Call 3:

 /Objects/{ObjectId}/Fields?start=400&max=200

The number of rows in Data-section might be 0. Now iteration can be stopped.

Get an object as a PDF

https://live.barium.se/api/v1.0/Objects/{ObjectId}/PDF

Get the PDF rendition for an object, if available.

Verb: Get

Query parameters available:

VersionId (string)

Returns:

Binary data: Adobe PDF file

Get an object as an image

https://live.barium.se/api/v1.0/Objects/{ObjectId}/image

Get the PNG Image rendition for an object, if available.

Verb: Get

Query parameters available:

VersionId (string)

Width (int)

Height (int)

Returns:

Binary data: PNG Image file

Get an object as a file

https://live.barium.se/api/v1.0/Objects/{ObjectId}/file

Get the file contents for an object, if available.

Verb: Get

Query parameters available:

VersionId (string)

Returns:

Binary data: File

Upload files to a container object

https://live.barium.se/api/v1.0/Content-Type/Objects/{ObjectId}/Objects

Uploads one or many files to a container object, such as a folder. Files are automatically uploaded to the object container if the client sends an HTTP POST with the Content-Type header of the request set to multipart/form-data.

The generated Id for each uploaded file is returned in the items array of the response.

empty files cannot be uploaded.

Verb: Post

Query parameters available:

N/A

Returns:

Object:

  • Success
  • Items (Array)
    • File name
    • Object Id
    • Reference Id

Create objects in a container

https://live.barium.se/api/v1.0/Objects/{ObjectId}/Objects

Creates a new object in a container. Clients create new objects by sending requests to the container URL, with the object entry in the request body.

Verb: Post

Query parameters available: N/A

Returns:

Object:

  • Success
  • Items (Array)
    • Name of object
    • Object Id
    • Reference Id

Example request:

  1. Creating folders
    {objectclass: "repository.folder",
    name: "My new folder"}
  2. Creating forms
    Set the template Id attribute in a form entry to create a form object. The correct template Id for each template can be fetched using the template's endpoint.
    It is possible to create single or multiple objects within one HTTP POST request as per below. The examples below describe all possible attributes and whether they are mandatory or not.
  3. Entry for creating a single-form object.

    Object class and TemplateId are mandatory parameters:

{objectclass: "dataforms.dataform",
name: "My form",
templateid: "template1",
fields: [
{name: "fieldId1", value: "value1"},
{name: "fieldId2", value: "value2"}
]
}

Entry for creating multiple objects:

[
{objectclass: "dataforms.dataform",
name: "My form",
templateid: "template1",
fields: [
{name: "fieldId1", value: "value1" },
{name: "fieldId2", value: "value2"}
]
},
{objectclass: "dataforms.dataform",
name: "My other form",
templateid: "template2",
fields:[
{name: "fieldId1", value: "value1" },
{name: "fieldId2", value: "value2"}
]
}
]

Update fields in a form

https://live.barium.se/api/v1.0/Objects/{ObjectId}/Fields

Updates fields in an object, such as fields for a form.

Verb: Post

Query parameters available: N/A

Returns:

Object (Array)

            Success status

Example request:

POST

The HTTP Header “Content-Type” should be set to “application/x-www-form-urlencoded”

Field1=Value1&Field2=Value2&Field3=Value3

Updating typed fields in a form

https://live.barium.se/api/v1.0/Objects/{ObjectId}/Fields

Updates fields that are typed in forms. Examples of typed fields are value lists, both single select and multi-select.

Typed fields have a data object called “Typenamespace”, which indicates that the field requires a pre-set value. A typed field also has the parameter FieldType with the value Select or Multiselect, indicating that it may contain a single value or multiple values.

To post a single value to a field, post the TypeNamespaceId to the field Id: FieldId1=TypeNamespaceId1

To post multiple values to a multi select field, post the TypeNamespaceIds separated by commas to the field Id: FieldId1=TypeNamespaceId1,TypeNamespaceId2

For information on how to get types and their content, see the types endpoint.

Verb: Post

Query parameters available: N/A

Returns:

Object:

           Success status

Update an existing object

https://live.barium.se/api/v1.0/Objects/{ObjectId}/

or

https://live.barium.se/api/v1.0/Objects/{ObjectId}/Objects/{ReferenceId}

Depending on what the requirement is, it is possible to update existing objects or to update existing objects which are housed in a folder.

It is currently not possible to update multiple objects at the same time. The object class, TypeNamespace (value list Id) and template Id attributes cannot be changed when updating objects.

Use the endpoint without reference Id to reach an object, such as Objects/00a9e90c-17b8-413c-ba9a-b60d2600ad63/Objects/template1 to reach the "template1" template-based object. Or use the endpoint with reference Id to reach an object within an object container (e.g folder) with a reference id, such as /Objects/00a9e90c-17b8-413c-ba9a-b60d2600ad63/Objects/Customer to reach the "Customer" pure data object within the /Objects/00a9e90c-17b8-413c-ba9a-b60d2600ad63 container.

Verb: Put

Query parameters available: N/A

Returns:

Object:

Success status

Example request:

  1. Entry for updating a folder
    PUT /Objects/00a9e90c-17b8-413c-ba9a-b60d2600ad63
    {name: "Attachment"}
  2. Entry for updating file metadata:
    PUT /Objects/00a9e90c-17b8-413c-ba9a-b60d2600ad63
    {name: "MyFile.PDF",
    description: "My file attachment"}
  3. Entry for updating a form:
    The attributes readonly, name, and value are mandatory
PUT /Objects/00a9e90c-17b8-413c-ba9a-b60d2600ad63/Objects/Customer
{fields: [
{name: "Zip", value: "41117"}
]
}

Update an existing file

https://live.barium.se/api/v1.0/Objects/{ObjectId}/

or

https://live.barium.se/api/v1.0/Objects/{ObjectId}/Objects/{ReferenceId}

Updates an existing file object by uploading a new file to an existing resource URL.

Files are automatically uploaded if the client sends an HTTP POST with the Content-Type header of the request set to multipart/form-data.

Empty files cannot be uploaded.

Verb: Post

Query parameters available: N/A

Returns:

Object:

Success status

Delete an object

The API will not be able to delete an object when someone else has full control.

https://live.barium.se/api/v1.0/Objects/{ObjectId}/

or

https://live.barium.se/api/v1.0/Objects/{ObjectId}/Objects/{ReferenceId}

Deletes an existing object, e.g a form or a file. It is currently not possible to delete multiple objects at the same time.

Use the endpoint with Reference Id to delete an object within an object container with a reference Id, such as /Objects/00a9e90c-17b8-413c-ba9a-b60d2600ad63/Objects/7B to delete the "7B" template-based object or /Objects/00a9e90c-17b8-413c-ba9a-b60d2600ad63/Objects/Kund to delete the "Kund" pure data object within the /Objects/00a9e90c-17b8-413c-ba9a-b60d2600ad63 container.

Objects with the Read only attribute set to true cannot be deleted.

Verb: Delete

Query parameters available: N/A

Returns:

Object:

Success status

Processes

When to use Processes

The endpoints for processes enable the API user to fetch the process models that the user has access to.

Examples:

  • Fetch a list of all process models
  • Fetch information about the process models

Syntax:

  • GET /Processes
  • GET /Processes/{ProcessId}

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded

The API user will only access the information for which it has been given permission. To set permissions, navigate to the process model for the process application and give the API user access to view and edit instances.

List process models

https://live.barium.se/api/v1.0/Processes

List available process models

Verb: Get

Query parameters available:

Start(int)

Max(int)

Returns:

Total count

Data (Array):

  • Process Id
  • Name of process
  • Description
  • Official
  • Created date
  • Published date
  • Changed date
  • Category

On error:

Empty array

Get information about a process model

https://live.barium.se/api/v1.0/Processes/{ProcessId}

Get information for a specific process model, or for a version of a process model.

Verb: Get

Query parameters available:

VersionId (string)

Returns:

Object:

  • Process Id
  • Name of process
  • Description
  • Official
  • Any official
  • Created date
  • Created by
  • Created by user Id
  • Published date
  • Published by
  • Published by user Id
  • Changed date
  • Changed by
  • Changed by user Id
  • Category
  • Current official object version Id
  • Current revision object version Id
  • Last version comment

Spaces

When to use Spaces

Spaces endpoints are used to get data about everything happening in a space.

Space is called Domain in the endpoints.

Examples:

  • Get information on all the process models or process applications
  • Fetch a list of all the instances or tasks in a space
  • Fetch all form templates used in all applications in a space

Syntax:

  • GET /Domains/{SpaceId}/Processes
  • GET /Domains/{SpaceId}/Apps
  • GET /Domains/{SpaceId}/Startevents
  • GET /Domains/{SpaceId}/Instances
  • GET /Domains/{SpaceId}/Tasks
  • GET /Domains/{SpaceId}/InstanceObjects
  • GET /Domains/{SpaceId}/InstanceObjectsFields
  • GET /Domains/{SpaceId}/DataFormTemplates
  • GET /Domains/{SpaceId}/DataFormTemplatesFields

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded

The API user will only have access operations for which it has been given permissions.

To set permissions for the space

Navigate to user management and grant the API user Admin permissions.

To set permissions for Processes, Applications Instances, Instance objects, and Form templates

Navigate to the process model for the process application and give the API user access to see and edit instances through Process settings.

To set permissions for tasks and start events

There are two different ways to do this:

  • Navigate to the process model for the process application and add the API user to the lane in which the task is performed. This is done by deploying the application.
  • Or, manually assign tasks to the API user.

Get information about all process models

https://live.barium.se/api/v1.0/Domains/{SpaceId}/Processes

Fetches metadata for all process models in a space.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array):

  • Process Id
  • Name of process
  • Description
  • Official
  • Official version Id
  • Revision version Id
  • Created date
  • Published date
  • Changed date
  • Category
  • Space Id

Get information about all process applications

https://live.barium.se/api/v1.0/Domains/{SpaceId}/Apps

Fetches metadata for all process applications in a space.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array):

  • Application Id
  • Name of application
  • Description
  • Status of application
  • Instances count
  • Process Id
  • Space Id

Get information about all start events

https://live.barium.se/api/v1.0/Domains/{SpaceId}/Startevents

Fetches metadata for all manual start events in a space.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array)

  • Start event Id
  • Reference Id
  • Name of start event
  • Description
  • Application Id
  • Process Id
  • Space Id

Get information about all instances

https://live.barium.se/api/v1.0/Domains/{SpaceId}/Instances

Fetches metadata for all instances in a space.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array)

  • Instance Id
  • Reference Id
  • Name of instance
  • Description
  • Status of instance
  • Instance state
  • Start date
  • Started by
  • Started by user Id
  • Start event BPD Id
  • Start event name
  • Deadline date
  • End event BPD Id
  • End event name
  • Completed date
  • Application Id
  • Process Id
  • Space Id

Get information about all tasks

https://live.barium.se/api/v1.0/Domains/{SpaceId}/Tasks

Fetches metadata for all tasks in a space.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array)

  • Task Id
  • Reference Id
  • Name of task
  • Description
  • Type of task
  • Status of task
  • Created date
  • Deadline date
  • Completed date
  • Completed by
  • Completed by User Id
  • Instance Id
  • Instance name
  • Application Id
  • Application name
  • Process Id
  • Locked
  • Locked by
  • Locked by user Id
  • Participants
  • Space Id

Get information about all instance objects

https://live.barium.se/api/v1.0/Domains/{SpaceId}/InstanceObjects

Fetches metadata for all instance objects in a space. For example forms or files.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array)

  • Object Id
  • Parent Id
  • Reference Id
  • Name of object
  • Description
  • Object class
  • Container
  • Read only
  • TypeNamespace (Value list Id, will only be populated if the field is a value list)
  • Template Id
  • File type
  • Sort index
  • State
  • Created date
  • Updated date
  • Instance Id

Get information about all form fields

https://live.barium.se/api/v1.0/Domains/{SpaceId}/InstanceObjectsFields

Fetches all field values in all objects in all instances in a space.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array)

  • Field Id
  • Object Id
  • Name of field
  • Data type
  • Field type
  • Value
  • Field TypeNamespace (Value list Id, will only be populated if the field is a value list)
  • Read only
  • Index
  • Instance Id

Get all templates

https://live.barium.se/api/v1.0/Domains/{SpaceId}/DataFormTemplates

Fetches all templates in all applications in a space.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array)

  • Form template Id
  • Reference Id
  • Object class
  • Name of form template
  • Description
  • Created date
  • Changed date

Get all template fields

https://live.barium.se/api/v1.0/Domains/{SpaceId}/DataFormTemplatesFields

Fetches all template fields in all applications in a space.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array)

  • Field Id
  • Template Id
  • Name of field
  • Data type
  • Field type
  • Field TypeNamespace (Value list Id, will only be populated if the field is a value list)
  • Read only
  • Index

Start events

When to use Start events

The start events endpoints enable organizations to fetch available start events and metadata for creating instances, which can be used to start a new instance from a process application’s start event. This endpoint is cached for 15 seconds. If you make the exact same call within these 15 seconds, you will receive cached data.

To start an instance with a data form, it is necessary to use the application's endpoint.

The API user will only fetch start events that it has been given access to.
Examples:
- List all start events that the API user can trigger
- List all form templates and their associated fields that must be populated when starting an instance
- Use the information about form templates and fields to trigger a start event

Syntax:

  • GET /startevents
  • GET /startevents/{StarteventId}
  • GET /startevents/{StarteventId}/assignableparticipants
  • GET /startevents/{StarteventId}/assignableparticipants/{ParticipantId}
  • GET /startevents/{StarteventId}/DataFormTemplates
  • GET /startevents/{StarteventId}/DataFormTemplates/{DataFormTemplateId}/fields
  • POST /startevents/{StarteventId}

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded

The API user will only access the start events that it has been given permission to. To set permissions, associate the API user with the lane in which the start event is located.

List all start events

https://live.barium.se/api/v1.0/startevents

This endpoint lists all the start events that the API user has access to.

Verb: Get

Query parameters available:

Start(int)

Max(int)

Returns:

Total count

Data (Array)

  • Start event Id
  • Name of start event
  • Description
  • Application Id
  • Process Id

Get information about start events

https://live.barium.se/api/v1.0/startevents/{StarteventId}

Fetches metadata for a specific start event with information about comments and assignable participants.

Verb: Get

Query parameters available: N/A

Returns:

Object:

  • Start event Id
  • Name of start event
  • Description
  • Application Id
  • Process Id
  • Can comment
  • Must comment
  • Must assign performers

List assignable participants

https://live.barium.se/api/v1.0/startevents/{StarteventId}/assignableparticipants

Fetches the participants that must be assigned with performers when performing an action.

Verb: Get

Query parameters available:

VersionId (string)

Returns:

Total count

Data (Array)

  • Name of participant
  • Participant Id

List available performers

https://live.barium.se/api/v1.0/startevents/{StarteventId}/assignableparticipants/{Id}

Fetches available performers to choose from and set them to a specific participant.

Verb: Get

Query parameters available:

VersionId (string)

Returns:

Total count

Data (Array)

  • Name of performer
  • Performer Id

List form templates in a start event

https://live.barium.se/api/v1.0/startevents/{StarteventId}/DataFormTemplates

Fetches the form templates that must be created when triggering a start event.

Verb: Get

Query parameters available:

VersionId (string)

Returns:

Form templates (Array)

  • Form template Id
  • Reference Id
  • Data object Id
  • Object class
  • Name of form template
  • Description
  • View mode

List form template fields in a start event

https://live.barium.se/api/v1.0/startevents/{StarteventId}/DataFormTemplates

Fetches the form template fields that must be populated when triggering a start event.

Verb: Get

Query parameters available: N/A

Returns:

Data (array)

  • Form field Id
  • Name of form field
  • Description
  • Data type
  • Field type
  • Field TypeNamespace (Value list Id, will only be populated if the field is a value list)
  • Read only
  • Allow blank
  • Index

Start a new instance

https://live.barium.se/api/v1.0/startevents/{StarteventId}

Starts a new instance using a specific start event. The query string instancename must be populated with a value. This will be the name of the instance.

Verb: Post

Query parameters available:

Instance name (string)

Instance description (string)

Comment (string)

Participant Assignments (array)

Returns:

Success

Items (Array)

  • Success
  • Object class
  • Name of instance
  • Instance Id
  • Reference Id

Example request:

  1. Start event
    POST /startevents/{StarteventId}?instancename=name_of_instance
  2. Assign participants with a start event
    Participant assignment is set as a query string in the /Startevents
    POST /startevents/{StarteventId}?participants=[{participant:'Id',securityIds:'Identifier'}]
    Each participant that is to be assigned must be a separate JSON object in an array.

    participant:'Id' is the Id of the participant to set which you get from /startevents/{StarteventId}/assignableparticipants

    securityIds:'Identifier' is the Id of the chosen performer to be set as a participant which you get from /startevents/{StarteventId}/assignableparticipants/{Id}

Tasks and Actions

When to use Tasks

The task endpoints are used to fetch information about tasks and associated objects. The API user will only be able to fetch the tasks it has been given access to.

Examples:

  • List all available tasks
  • Get all available references for a task, for example, files with instructions or links to resources

Syntax:

  • GET /Tasks
  • GET /Tasks/{TaskId}
  • GET /Tasks/{TaskId}/Objects
  • GET /Tasks/{TaskId}/Objects/{ObjectId}
  • GET /Tasks/{TaskId}/Objects/{ObjectId}/Fields
  • GET /Tasks/{TaskId}/References
  • GET /Tasks/{TaskId}/References/{ReferenceId}

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded

The API user will only access the tasks for which it has been given permission. To set permissions, associate the API user with the lane where the task is located. Or, manually assign the task to the API user.

If the API user has been given access to see and edit instances through Process settings, it will be able to see the tasks within those instances.

List all tasks

https://live.barium.se/api/v1.0/Tasks

Fetches available tasks. It is possible to filter active and completed tasks by status. The status values are Ready; Completed. If no tasks are available, an empty array is returned.

Verb: Get

Query parameters available:

Status (string)

Start (int)

Max (int)

Returns:

Total count

Data (Array)

  • Task Id
  • Name of task
  • Description
  • Task status
  • Created date
  • Completed date
  • Completed by
  • Instance name
  • Application name
  • Locked
  • Perform permission

Get information about a task

https://live.barium.se/api/v1.0/Tasks/{TaskId}

Get the metadata for a specific task.

Verb: Get

Query parameters available: N/A

Returns:

Object:

  • Task Id
  • Name of task
  • Description
  • Task status
  • Created date
  • Completed date
  • Completed by
  • Completed by user Id
  • Instance name
  • Instance Id
  • Application name
  • Application Id
  • Locked
  • Perform permission

List objects in a task

https://live.barium.se/api/v1.0/Tasks/{TaskId}/Objects

List available objects in a task, such as forms, files, and folders. If no objects are available then an empty array is returned.

Verb: Get

Query parameters available:

Start (int)

Max (int)

Returns:

Total count

Data (Array)

  • Object Id
  • Name of object
  • Description
  • Type
  • Container
  • Renditions (Array)

Get information about an object

https://live.barium.se/api/v1.0/Tasks/{TaskId}/Objects/{ObjectId}

Fetches metadata for one specific object in a task.

Verb: Get

Query parameters available: N/A

Returns:

Object:

  • Parent Id
  • Reference Id
  • Name of object
  • Description
  • Type
  • Object class
  • Container
  • Read only
  • TypeNamespace (Value list Id, will only be populated if the field is a value list)
  • Template Id
  • File type

Get a task’s form fields

https://live.barium.se/api/v1.0/Tasks/{TaskId}/Objects/{ObjectId}/Fields

Use if the object is an Object class: dataforms.dataform. This means that it is a form with fields.

This endpoint returns a list of fields that can be viewed and changed in the task. The endpoint will only return the fields that should be viewed in the specific task. It will also contain information about which fields are read only or mandatory (where allow blank = false).

Verb: Get

Query parameters available: N/A

Returns:

Data (Array)

  • Field Id
  • Name of field
  • Data type
  • Field type
  • Value
  • Field TypeNamespace (Value list Id, will only be populated if the field is a value list)
  • Read only
  • Allow blank
  • Index

List references in a task

https://live.barium.se/api/v1.0/Tasks/{TaskId}/References

Fetches the available references for a task, such as instructions, governing documents, and URL links. If no references are available, an empty array is returned.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array)

  • Reference type
  • Name of reference
  • URL
  • Object reference

List references house in a container within the task

https://live.barium.se/api/v1.0/Tasks/{TaskId}/References/{ObjectId}

Fetches available references for a task that exists in a container object. If the reference type is a URL, the endpoint will return the URL address. If the reference type is a file, it will return the file type and the object reference.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array)

  • Reference type
  • Name of reference
  • URL
  • File type
  • Object reference

When to use Actions

The API method Action can be used to perform different actions on tasks. Here, it is possible to find the calls that get performable actions and assignable participants for a specific task or to perform a specific action for a specific task.

Examples:

  • Complete a task
  • Assign a performer to a task

Syntax:

  • GET /Tasks/{TaskId}/Actions
  • GET/ Tasks/{TaskId}/Actions/{ActionId}/AssignableParticipants
  • GET/ Tasks/{TaskId}/Actions/{ActionId}/AssignableParticipants/{ParticipantId}
  • POST/Tasks/{TaskId}/Actions/{ActionId}
  • POST/ Tasks/{TaskId}/Actions/{ActionId}?participants[ {participant:’ParticipantId’,securityIds:’Identifier}]

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded

The API user will only fetch the information for which it has been given permission. To set permissions, there are three options:

  • Navigate to the process model for the process application and give the API user access to see and edit instances through Process settings.
  • Navigate to the process model for the process application and add the API user to the lane in which the task is performed. This is done by deploying the application.
  • Manually assign the task to the API user.

List available actions on a task

https://live.barium.se/api/v1.0/Tasks/{TaskId}/Actions

Available actions on a task:

  • Complete a task
  • Assign a performer
  • Comment upon completing a task

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (array):

  • Action Id
  • Name of action
  • Description
  • Can comment
  • Must comment
  • Must assign performers

List the participants that must be assigned with performers when performing an action

https://live.barium.se/api/v1.0/Tasks/{TaskId}/Actions/{ActionId}/AssignableParticipants

Verb: GET

Query parameters available: N/A

Returns:
Data (array):

  • Participant Id
  • Name of participant

List the performers that can be assigned to a role

https://live.barium.se/api/v1.0/Tasks/{TaskId}/Actions/{ActionId}/AssignableParticipants/{ParticipantId}

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (Array):

  • Name of participant
  • Participant Id

Perform an action on a task

https://live.barium.se/api/v1.0/Tasks/{TaskId}/Actions/{ActionId}

The Success return value will return True if the task was performed successfully. If a subsequent task OR instance was created as a result of the task their respective Ids are returned.

Verb: Post

Query parameters available:
Comment (string)

Returns:

Object:

  • Success status
  • Instance Id
  • Task Id

Assign participants with action

https://live.barium.se/api/v1.0/Tasks/{TaskId}/Actions/{ActionId}?participants[{participant:’Id’,securityIds:’Identifier}]

Participant assignment is set as a query string in the URL. Each participant that is to be assigned must be a separate JSON object in an array.

  • Participant Id is the Id of the participant to set which you get from https://live.barium.se/api/v1.0/Tasks/{TaskId}/Actions/{ActionId}/AssignableParticipant
  • SecurityIds is the Id of the chosen performer to be set as a participant. You get this from https://live.barium.se/api/v1.0/Tasks/{TaskId}/Actions/{ActionId}/AssignableParticipants/{Id}

Verb: Post

Query parameters available:
Comment (string)

Participants (array)

(Participant (string)

SecurityIds (string))

Returns:

Object:

  • Success status
  • Instance Id
  • Task Id

Users and Groups

When to use Users

The API methods can be used to handle user administration within a space. It requires the API user to have access to Space administration.

Version 1.1 of the API must be used for these functions.

Examples:

  • List all users in a space, including which groups they are assigned to
  • Create and update users, assign them to groups
  • Disable users

Syntax:

  • GET /domains/{SpaceId}/users
  • GET /domains/{SpaceId}/usergroups
  • POST /domains/{SpaceId}/users
  • POST /domains/{SpaceId}/disableusers

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded

The API user will only have access to manage users and groups if the Admin box is checked. To set this, go to the Members tab in Space settings.
Check_admin_box.png

List all users in a space

https://live.barium.se/api/v1.1/domains/{SpaceId}/users

Fetches a list of all users in a space.

Verb: Get

Query parameters available:

Skip (int)

Take (int)

Returns:

Total count

Data (Array)

  • User Id
  • First name
  • Last name
  • Email
  • Disabled
  • Last login date
  • Origin
  • Origin key
  • Title
  • Department
  • Country
  • Telephone number

List all users and their associated groups

https://live.barium.se/api/v1.1/domains/{SpaceId}/usergroups

Fetches a list of all users and their associated groups in a space.

Verb: Get

Query parameters available:

Skip (int)

Take (int)

Returns:

Total count

Data (Array)

  • User Id
  • First name
  • Last name
  • Email
  • Disabled
  • Last login date
  • Origin
  • Origin key
  • Title
  • Department
  • Country
  • Telephone
  • Groups (array)
    • Group Id
    • Name

Create new users

https://live.barium.se/api/v1.1/domains/{SpaceId}/users

Creates users in a contract and adds users to a space. Please note that users will be added to the contract and reused in the correct space. Identifying values are origin and origin key.

A post call is done using Content-type application/json

Verb: Post

Parameters available:
JSON object: 

{origin (string),
Users [
{email (string),
originkey (string)(identifying value),
localizationcode (string),
firstname (string),
lastname (string),
disabled (bool),
title (string),
department (string),
country (string),
telephone (string),
groups (string),
spacepermissions
{view (bool),
model (bool),
build (bool),
run (bool), admin (bool)}
}
]
}

Returns:

JSON Object:

{added (int),
updated (int),
errors (int),
users [
{key (string),
status (string)}
]
}

Example request:

POST /api/v1.1/domains/{SpaceId}/users
Content-Type: application/json
Ticket: {Ticket}
Body:
{
"origin": "11111111-1111-1111-1111-111111111111",
"users" : [
{"email": "john.doe@barium.se",
"originkey": "johdoe1",
"localizationcode": "sv-SE",
"firstname": "John",
"lastname": "Doe",
"disabled": false,
"title": "",
"department": "Sales",
"country": "",
"telephone": "",
"groups": [],
"spacepermissions":
{"view": false,
"model": false,
"build": false,
"run": true,
"admin": false}
}
]
}

Update users

https://live.barium.se/api/v1.1/domains/{SpaceId}/users

Updates existing users. Identifying values are origin and origin key. Only values that are updated need to be stated in the JSON body. Post is done using Content-type application/json .

Verb: Post

Parameters available:

JSON Object:

{origin (string),

users [
{email (string),
originkey (string)(identifying value),
localizationcode (string),
firstname (string),
lastname (string)
description (string),
disabled (bool),
title (string),
department (string),
country (string),
telephone (string),
groups (string),
spacepermissions
{view (bool),
model (bool),
build (bool),
run (bool)}
}
]
}

Returns:

JSON object: 

{added (int),
updated (int),
errors (int),
users [
{key (string),
status (string)}
]
}

Example request:

POST /api/v1.1/domains/{SpaceId}/users

Content-Type: application/json

Ticket: {Ticket}

Body:

{"origin": "11111111-1111-1111-1111-111111111111",
"users" : [
{ "originkey": "johdoe1",
"department": "Marketing"}
]
}

Assign a group to a user

https://live.barium.se/api/v1.1/domains/{SpaceId}/users

Updates existing users by assigning a group to the user. Identifying values are origin and origin key. Group Id:s for users must be stated and sent in the call. Post is done using Content-type application/json.

Verb: Post

Parameters available:

JSON object: 

{origin (string),
users [
{originkey(string),
groups [
{groupid (int)}
]
}
]
}

Returns:

JSON object: 

{added (int),
updated (int),
errors (int),
users [
{key (string),
status (string)}
]
}

Example request

POST /api/v1.1/domains/{SpaceId}/users

Content-Type: application/json

Ticket: {Ticket}

Body:

{ "origin": "11111111-1111-1111-1111-111111111111",
"users": [
{"originkey": "johdoe1",
"groups": [
{"groupid": 123},
{"groupid": 321}
]
}
]
}

Disable users

https://live.barium.se/api/v1.1/domains/{SpaceId}/disableusers

Disables a user in a space. Identifying values are origin and user Id. User Id can be fetched from the GET call. Post is done using Content-type application/json

Verb: Post

Parameters available:

JSON object:

{origin (string),
users [
{userid (int)}
]
}

Returns:
JSON object: 

{deleted (int),
errors (int),
users [
{userid (int),
status (string)}
]
}


Example request:

POST /api/v1.1/domains/{SpaceId}/disableusers

Content-Type: application/json

Ticket: {Ticket}

Body:

 {"origin": "11111111-1111-1111-1111-111111111111",
"users" : [
         {"userid": 123456}
]
}

When to use Groups

This API method can be used to manage group administration within a space. The API user needs to have space administrator permissions to perform any of the below calls.

Examples:

  • Create a new group or delete a redundant group
  • Update a group

Syntax:

  • GET /api/v1.1/domains/{SpaceId}/groups
  • POST /api/v1.1/domains/{SpaceId}/groups
  • DELETE /api/v1.1/domains/{SpaceId}/groups

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/x-www-form-urlencoded

The API user will only have access to manage users and groups if the Admin box is checked. To set this, go to the Members tab in Space settings.
Check_admin_box.png

Get all groups for a space

https://live.barium.se/api/v1.1/domains/{SpaceId}/groups

Lists all the groups in a space.

Verb: Get

Query parameters available:

Skip (int)

Take (int)

Returns:

Total count

Data (array):

  • Group Id
  • Security Id
  • Key
  • Name of group
  • Parent Id
  • Origin
  • Origin key

Create new groups

https://live.barium.se/api/v1.1/domains/{SpaceId}/groups

This call creates new groups. Origin and origin key values are optional. The post is done using Content-type application/json.

Verb: Post

Parameters available:

JSON Object:

{groups[
{key (string),
name (string),
origin (string),
originkey (string),
parentid (int)}
]
}

Returns:

Object:

  • Added
  • Updated
  • Errors
  • Groups (Array)
    • Group Id
    • Key
    • Group status

Example request:

POST /api/v1.1/domains/{SpaceId}/groups

Content-Type: application/json

Ticket: {Ticket}

Body: 

{"groups": [
{
"key": "G_1234",
"name": "My Group",
"origin": "11111111-1111-1111-1111-111111111111",
"originkey": "Group_1234",
"parentid": 1115991}
]
}

Update groups

 https://live.barium.se/api/v1.1/domains/{SpaceId}/groups

This call updates one or more groups in a space. The identifying value is the group Id. Both the name of the group and the parent group can be updated. If the parent group is to be updated, the parent Id must be added in the request post. A post is done using Content-type application/json.

Verb: Post

Parameters available:

JSON object: 

{ groups [
{
GroupId (int),
name (string),
parentid (int)}
]
}

Returns:

Object:

  • Added
  • Updated
  • Errors
  • Groups (Array)
    • Group Id
    • Key
    • Group status

Example request:

POST /api/v1.1/domains/{SpaceId}/groups

Content-Type: application/json

Ticket: {Ticket}

Body: 

{
"groups": [
{"id": "12345678",
"name": "My Group",
"parentid": 12345670}
]
}

Delete groups

https://live.barium.se/api/v1.1/domains/{SpaceId}/groups

This call deletes groups in a space. The identifying value is Id. Post is done using Content-type application/json.

Verb:

Parameters available:
JSON object: 

{ groups [
{id (int)}
]
}

Returns:

Object:

  • Deleted
  • Errors
  • Groups (Array)
    • Group Id
    • Name of group
    • Group status

Example request:

DELETE /api/v1.1/domains/{SpaceId}/groups
Content-Type: application/json
Ticket: {Ticket}
Body: 
{
"groups": [
{"id": "12345678"}
]
}

Value lists

Value lists are used as dropdown menus and multi-select fields in forms. There are two types of value lists, standard and extended. This is distinguishable in the user interface.

Standard value lists - Flat lists that may have a unique key.

Extended value lists -Values in one column may correspond with values in successive columns. Based on the content defined in the extended value list, the end user may select a value in the form, and other fields may be populated or used for operations as a result.

The API user needs to have space administrator permissions to perform the below calls. The API user will only have access to manage value lists if the Admin box is checked. To configure this, go to the Members tab in Space settings.
Check_admin_box.png

Standard value lists

Examples:

  • Get a list of all standard value lists in a space
  • Get the name, Id, and description for a standard value list
  • Get all the values for a standard value list
  • Add or update values in a standard value list
  • Delete values in a standard value list

Syntax:

  • GET /Types
  • GET /Types/{TypeNamespace}
  • GET /Types/{TypeNamespace}/TypeInstances
  • POST /domains/{SpaceId}/valuesets
  • DELETE /domains/{SpaceId}/valuesets

The endpoint /Types is cached for 15 seconds. If you make the exact same call within these 15 seconds, you will receive cached data.

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/json

Get all data types

https://live.barium.se/api/v1.0/Types

Get a list of all available types.

Verb: Get

Query parameters available:

Start (int)

Max (int)

Returns:

Total count

Data (Array)

  • TypeNamespace (Value list Id)
  • Name of value list
  • Description

Get information about a data type

https://live.barium.se/api/v1.0/Types/{TypeNamespace}

Retrieves the metadata for a specific data type.

Verb: Get

Query parameters available: N/A

Returns:

Object:

  • TypeNamespace (Value list Id)
  • Name of value list
  • Description

List values in a standard value list

https://live.barium.se/api/v1.0/Types/{TypeNamespace}/TypeInstances

Gets a list of values for the data type.

Verb: Get

Query parameters available: N/A

Returns:

Object (Array)

  • Value Id
  • Parent Id
  • Key value
  • Name of the value
  • Description

Add or update values in a standard value list

https://live.barium.se/api/v1.1/domains/{SpaceId}/valuesets

Updates any existing values for existing keys and adds values for nonexisting keys.

Verb: Post

Query parameters available: N/A

Returns: N/A

Example request: 

POST data:

{
	"namespace": "00000000-0000-0000-0000-000000000000.type",
	"values": 
		[
			{ "key": "1234", "name": "1234", "description": ""},
			{ "key": "1256", "name": "My value 2", "description": ""}
		]
}

This request will:

  • If a value with key = "1234" exists, the name will be set to "1234" and the description will be set to "". If no value exists with a key = "1234" a new value will be added.
  • If a value with key = "1256" exists, the name will be set to "My value 2" and the description will be set to "". If no value exists with a key = "1256" a new value will be added.

Delete values from a standard value list

https://live.barium.se/api/v1.1/domains/{SpaceId}/valuesets

Deletes values from the keys provided in the call.

Verb: Delete

Query parameters available: N/A

Returns: N/A

Example request: 

DELETE data:

{
	"namespace": "00000000-0000-0000-0000-000000000000.type",
	"values": 
		[
			{ "key": "1234" },
			{ "key": "1256" }
		]
}

This request will:

  • Delete the value with the key "1234" 
  • Delete the value with the key "1256"

Extended Value lists

It is possible to access the extended value lists programmatically to for example:

  • See and update the values available in the extended value list

Syntax:

  • GET /domains/{SpaceId}/extendedvaluelists
  • GET /domains/{SpaceId}/extendedvaluelists/{ExtendedvaluelistId}
  • PATCH domains/{SpaceId}/extendedvaluelists/{ExtendedvaluelistId}

Header:

  • Ticket previously generated from authentication
  • Content-Type: application/json

The API user will have access to extended value lists by default. No other settings are necessary.

List all extended value lists

https://live.barium.se/api/v1.0/domains/{SpaceId}/extendedvaluelists

This call lists all extended value lists within a space.

Verb: Get

Query parameters available: N/A

Returns:

Total count

Data (array)

  • Name of list
  • Description
  • TypeNamespace (Value list Id, will only be populated if the field is a value list)

Get a list

https://live.barium.se/api/v1.0/domains/{SpaceId}/extendedvaluelists/{ExtendedvaluelistId}

Get a specific value list in a space.

Verb: Get

Query parameters available: N/A

Returns:

Name of list

Reference

Automatically generate keys

External data set

Description

Column headers (array)

Data (array)

         The result will be returned line by line for each item in the list. The first value in each array gives             the key, and then the values. The amount of values depends on the amount of columns.

Update an extended value list

https://live.barium.se/api/v1.0/domains/{SpaceId}/extendedvaluelists/{ExtendedvaluelistId}

Updates a whole extended value list with new data by using the operations "Insert", "Update" and "Delete".

The operations affect rows for an extended value list where the row key is used as an identifier. The row keys are found at the top of the table in the UI. It is possible to update multiple rows in one request.

Verb: Patch

Query parameters available: N/A

Returns: N/A

Example request: 

PATCH data:

[
{ "opt": "insert", "path": "/data/key1", "values": ["A", "B", "C", "D"]},
{ "opt": "update", "path": "/data/key2", values": ["Aa", "Bb", "Cc", "Dd"]},
{ "opt": "delete", "path": "/data/key3"}
]

This request will:

  • Insert a new row with A, B, C, D as values
  • Update the row with the key "key2"
  • Delete the row with the key "key3"

Was this article helpful?

0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.