Endpoints for Entity Objects

Use these endpoints to get, create, update, or delete entity objects in your ProcessMaker IDP instance. Optionally, filter, sort, and/or paginate results when you receive results.

Base URL for Entity Object Endpoints

You can access the server via https://{idp-server}/datastore/api/rest. Each entity type has its own endpoint and is identified by its type: /{type}.

Gets a collection of entity objects by their type.

GET https://{idp-server}/datastore/api/rest/{type}

See 200 status code response for cURL example.

Path Parameters

Name	Type	Description
type*	String	Entity type to get.

200: OK OK.

Example of getting a collection of file entities:

cURL request:

curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/file"

400: Bad Request Incorrect or incomplete.

401: Unauthorized Unauthorized.

404: Not Found Collection with the specified type does not exist.

500: Internal Server Error Internal server error.

Gets one type's entity object by its unique ID.

GET https://{idp-server}/datastore/api/rest/{type}/{id}

See 200 status code response for cURL example and response example.

Path Parameters

Name	Type	Description
type*	String	Entity type related to the entity to get.
id*	String	Unique ID of the entity to get in that type.

200: OK OK.

Example of getting a file entity with ID d72c9a40-8ef1-4c16-94c8-038cd9b80089:

cURL request:

curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/file/d72c9a40-8ef1-4c16-94c8-038cd9b80089"

Example response:

The request was okay and the response body contains the representation requested.

{
  "data": {
    "type": "file",
    "attributes": {
      "createdAt": "2019-11-29T09:46:29.006+0000",
      "createdBy": "User",
      "documentType": "NONE",
      "modifiedAt": "2019-12-03T07:41:33.445+0000",
      "name": "Welcome to IDP.docx",
      "modifiedBy": null,
      "checkedOutBy": null,
      "id": "d72c9a40-8ef1-4c16-94c8-038cd9b80089",
      "content": 117350
    },
    "relations": {}
  },
  "status": "success",
  "message": null
}

500: Internal Server Error Internal server error.

400: Bad Request Incorrect, incomplete, non-existing type or ID.

404: Not Found Entity with the specified ID in the specified type not found.

401: Unauthorized Unauthorized.

Gets the content (binary) of a type's entity object by its unique ID.

GET https://{idp-server}/datastore/api/rest/{attribute}/{type}/{id}

Unlike other GET method endpoints, this endpoint uses a type entity called file. The attribute that contains the binary, which is the file to download, is called content.

See 200 status code response for cURL example.

Path Parameters

Name	Type	Description
attribute*	String	Attribute that contains the binary.
type*	String	Entity type related to the entity to get.
id	String	Unique ID of the entity to get in that type.

200: OK OK.

Example of getting a file entity with ID 17478078-52cf-4472-ab98-1b27a10b71c9:

cURL request:

curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/content/file/17478078-52cf-4472-ab98-1b27a10b71c9"

400: Bad Request Incorrect, incomplete, non-existing type or ID.

401: Unauthorized Unauthorized.

404: Not Found Entity with the specified ID in the specified type not found.

500: Internal Server Error Internal server error.

Gets resources related to an entity object.

GET https://{idp-server}/datastore/api/rest/{type}/{id}/{relation}

See 200 status code response for cURL example.

Path Parameters

Name	Type	Description
type*	String	Entity type related to the entity to get.
id*	String	Unique ID for the entity to get in that type.
relation*	String	Relation name for the entity to get.

200: OK OK.

Example of getting a folder with name 5f97858b-26e3-4180-80c4-25b176cbc35f:

cURL request:

curl --location --request GET
"https://processmaker-idp.com/api/rest/folder/5f97858b-26e3-4180-80c4-25b176cbc35f/files"

400: Bad Request Incorrect, incomplete, non-existing type, ID, or relation.

401: Unauthorized Unauthorized.

404: Not Found Entity by the specified ID in the specified type for the specified relation not found.

500: Internal Server Error Internal server error.

Filter by name of entity object result.

GET https://{idp-server}/datastore/api/rest/{type}?filter%5Bname%5D={name}

Note: Due to an issue in Spring Framework, URL parameters in GET requests do not properly url-encode. When filtering for an entity containing a + character in its name, there are two ways to process this (see examples). For example, for the file Welcome + to + IDP.docx the + symbol gets encoded.

See 200 status code response for URL examples. See examples 3 and 4 how to address the + character issue.

Path Parameters

Name	Type	Description
type*	String	Entity type related to the entity to get.
name	String	Name of the entity object from which to filter results. Use exact characters as the entity object is named, including spaces. Note exception above regarding the + character.

200: OK OK.

Example 1: Example for an entity filtered on name Welcome to IDP.docx:

GET https://<idp-server-url>/datastore/api/rest/{type}?filter%5Bname%5D=Welcome to IDP.docx

Example 2: Example that uses multiple filters:

GET https://<idp-server-url>/datastore/api/rest/{type}?filter%5Bname%5D=Welcome to IDP.docx&filter%5BcreatedB
y%5D=admin

Example 3: Option 1 to encode the + character in a GET request:

GET https://<idp-server-url>/datastore/api/rest/{type}?filter%5Bname%5D=Welcome %2B to %B2 IDP.docx

Example 4: Option 2 as alternative to encoding the + character by using a POST request:

POST https://<idp-server-url>/datastore/api/rest/{type}/readAllPost
{
  "filter[name]": "Welcome + to + IDP.docx"
}

400: Bad Request Incorrect, incomplete, or non-existing type.

401: Unauthorized Unauthorized.

404: Not Found Entity by the specified name in the specified type not found.

500: Internal Server Error Internal server error.

Sort results by providing the attribute(s) from which to sort, followed by sorting direction.

GET https://{idp-server}/datastore/api/rest/file?sort=

By default, results are sorted in ascending order. To sort in the opposite direction, add a minus character (-) preceding the attribute name.

See 200 status code response for cURL example.

200: OK OK.

Example of a request to read files sorted in descending order by creation date:

curl --location --request GET "https://processmaker-idp.com/datastore/api/rest/file?sort=-
createdAt"

400: Bad Request Incorrect, incomplete, or non-existing attribute(s).

401: Unauthorized Unauthorized.

404: Not Found Entity not found.

500: Internal Server Error Internal server error.

Paginate results.

GET https://{idp-server}/datastore/api/rest/file?count=

The ProcessMaker IDP REST API uses cursor-based pagination (also known as keyset pagination).

When no parameters for pagination are provided, default values for pagination apply. The returned response contains links that refer to the next and previous pages. Default count per page is 20.

See 200 status code response for cURL example.

Path Parameters

Name	Type	Description
after	Integer	Returns the first item immediately after the cursor in the results list. Typically use to get the next page.
before	Integer	Returns the last item in the paginated data to be closest to, but still before, the cursor in the non-paginated results list. Typically use to get the prior page.
count	Integer	Number of entities per page.

200: OK OK.

Example of a request with pagination parameters:

cURL request:

curl --location --request GET 
"https://processmaker-idp.com/datastore/api/rest/file?count=2\&after=1"

Example response:

{
  "data": [
    {
      "type": "file",
      "attributes": {
        "createdAt": "2019-12-03T07:35:31.344+0000",
        "createdBy": "User",
        "documentType": "NONE",
        "modifiedAt": null,
        "name": "Welcome to IDP.docx",
        "modifiedBy": null,
        "checkedOutBy": null,
        "id": "0e21bb8f-b8fd-42f7-872f-319389b313e8",
        "content": 117334
      }
    },
    {
      "type": "file",
      "attributes": {
        "createdAt": "2019-12-02T12:11:19.815+0000",
        "createdBy": "User",
        "documentType": "NONE",
        "modifiedAt": null,
        "name": "Welcome at IDP.docx",
        "modifiedBy": null,
        "checkedOutBy": null,
        "id": "0e73b1e6-c125-40e5-b634-b709c4089299",
        "content": null
      }
    }
  ],
  "status": "success",
  "message": null,
  "links": {
    "next": "/api/rest/file?count=2&after=3",
    "prev": "/api/rest/file?count=2&before=2"
  }
}

400: Bad Request Incorrect or incomplete.

401: Unauthorized Unauthorized.

404: Not Found Entity not found.

500: Internal Server Error Internal server error.

Creates an entity object by specifying its entity type.

POST https://{idp-server}/datastore/api/rest/{type}

See 200 status code response for examples and a response example.

See below this endpoint description for example how to create a file entity with a file.

Path Parameters

Name	Type	Description
type*	String	Entity type to create.

Request Body

Name	Type	Description
data*	JSON String	Attributes specified as key/value pairs. When creating files or subfolders in a dossier, parentId JSON object is required.
file	Binary Data	File to upload with your entity.

200: OK OK.

Example to create a dossier:

type is an attribute of FOLDER. Specify the name of the new dossier in the name JSON object.

{
	"attributes": {
		"name": "datastoreCreateDossierName",
		"type": "DOSSIER"
	}
}

Example to create a folder:

type is an attribute of FOLDER. Specify the name of the new folder in the name JSON object. parentId is required only when creating a folder to specify in which folder or dossier to create the new folder.

{
	"attributes": {
		"name": "datastoreCreateFolderName",
		"type": "FOLDER",
		"parentId": "de6b5bef-eca7-41db-84c9-17e1c0376d71"
	}
}

Example to create a file:

Specify the name of the new file in the name JSON object.

{
	"attributes": {
		"name": "datastoreCreateFileNameJPG",
		"parentId": "de6b5bef-eca7-41db-84c9-17e1c0376d71"
	}
}

Example response after successfully creating an entity object:

The request was okay and the response body contains the representation requested. The response contains all attributes of the created entity. This includes auto-generated attributes.

{
  "data": {
    "type": "file",
    "attributes": {
      "createdAt": "2023-12-03T12:47:06.960+0000",
      "createdBy": "User",
      "documentType": "NONE",
      "modifiedAt": null,
      "name": "Welcome to IDP.docx",
      "modifiedBy": null,
      "checkedOutBy": null,
      "id": "127a9e31-395a-483e-8415-9456f44199d8",
      "content": 125398,
      "parentId": null
    }
  },
  "status": "success",
  "message": null
}

400: Bad Request Incorrect, incomplete, non-existing type.

401: Unauthorized Requires authentication.

500: Internal Server Error Internal server error.

Example how to create a file entity with a file.

curl --location --request POST
"https://processmaker-idp.com/datastore/api/rest/file";
$oRet = pmRestRequest("POST", $url, $afile);

\--form "data={

\\"attributes\\": {

\\"name\\": \\"Welcome to IDP.docx\\",

\\"createdBy\\": \\"User\\"

}

}" \\

\--form "file=@/filesystem/Documents/Welcome to IDP.docx"

Updates one type's entity object by its unique ID.

PUT https://{idp-server}/datastore/api/rest/{type}/{id}

See 200 status code response for cURL example and response example. See below this endpoint description for example how to update a file entity with another file, thereby replacing it.

Path Parameters

Name	Type	Description
type*	String	Entity type related to the entity to update.
id*	String	Unique ID for the entity to update in that type.

Request Body

Name	Type	Description
data	JSON String	Attributes specified as key-value pairs.
file	Multipartfile	The file to update.

200: OK OK.

Example of updating a file entity with ID d72c9a40-8ef1-4c16-94c8-038cd9b80089, where both the attributes and the binary will be updated:

cURL request:

curl --location --request PUT "https://processmaker-idp.com/datastore/api/rest/file/d72c9a40-8ef1-4c16-94c8-038cd9b80089"

Example response:

The request was okay and the response body contains the representation requested. The response contains all attributes of the updated entity.

{
  "data": {
    "type": "file",
    "attributes": {
      "createdAt": "2023-12-03T12:47:06.960+0000",
      "createdBy": "User",
      "documentType": "NONE",
      "modifiedAt": "2023-12-05T12:47:06.960+0000",
      "name": "Welcome back to IDP.docx",
      "modifiedBy": "User2",
      "checkedOutBy": "User",
      "id": "d72c9a40-8ef1-4c16-94c8-038cd9b80089",
      "content": 125398,
      "parentId": null
    }
  },
  "status": "success",
  "message": null
}

400: Bad Request Incorrect, incomplete, non-existing type or ID.

401: Unauthorized Unauthorized.

404: Not Found Entity with the specified ID in the specified type not found.

500: Internal Server Error Internal server error.

Example how to update a file entity with another file.

curl --location --request PUT
"https://processmaker-idp.com/datastore/api/rest/file";
$oRet = pmRestRequest("PUT", $url, $afile);

\--form "data={

\\"attributes\\": {

\\"name\\": \\"Welcome back to IDP.docx\\",

\\"createdBy\\": \\"User\\"

}

}" \\

\--form "file=@/filesystem/Documents/Welcome back to IDP.docx"

Deletes one type's entity object by its unique ID.

DELETE https://{idp-server}/datastore/api/rest/{type}/{id}

See 200 status code response for cURL example. See below this endpoint description for example how to delete a file entity.

Path Parameters

Name	Type	Description
type*	String	Entity type related to the entity to delete.
id*	String	Unique ID of the entity to delete in that type.

200: OK OK.

Example of deleting a file entity with ID d72c9a40-8ef1-4c16-94c8-038cd9b80089:

cURL request:

curl --location --request DELETE "https://processmaker-idp.com/datastore/api/rest/file/d72c9a40-8ef1-4c16-94c8-038cd9b80089"

400: Bad Request Incorrect, incomplete, non-existing type or ID.

401: Unauthorized Unauthorized.

404: Not Found Entity with the specified ID in the specified type not found.

500: Internal Server Error Internal server error.

Errors

ProcessMaker IDP uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

• Codes in the 2xx range indicate success.

• Codes in the 4xx range indicate an error that failed given the information provided (such as a required parameter was omitted or the provided ID does not exist).

• Codes in the 5xx range indicate an error with ProcessMaker IDP’s servers.

Most 4xx errors will return a message that briefly explains the reported error.

Example of an error message: Status 400 Bad Request:

{
  "data": null,
  "status": "error",
  "message": "Please provide JSON data and/or a file."
}