Creatio (creatio v0.3.1)

Copy Markdown

Elixir SDK for Creatio CRM (formerly bpm'online).

Provides an idiomatic, comprehensive client for interacting with Creatio instances via OData 4, OData 3, DataService JSON APIs, Forms Authentication, and OAuth 2.0.

Quick Start

Forms Authentication

client = Creatio.new(base_url: "https://myinstance.creatio.com")
{:ok, client} = Creatio.login(client, "User01", "Password123")

# List contacts
{:ok, contacts} = Creatio.list(client, "Contact", select: ["Id", "Name", "Email"], top: 10)

OAuth 2.0 Client Credentials

client = Creatio.new(
  base_url: "https://myinstance.creatio.com",
  identity_service_url: "https://myidentity.creatio.com",
  client_id: "your_client_id",
  client_secret: "your_client_secret"
)

{:ok, client, _token} = Creatio.login_oauth(client)

OData 4 Query Builder

{:ok, results} =
  Creatio.query("Contact")
  |> Creatio.OData.Query.select(["Id", "Name", "MobilePhone"])
  |> Creatio.OData.Query.filter_contains("Name", "Smith")
  |> Creatio.OData.Query.filter_eq("Active", true)
  |> Creatio.OData.Query.order_by("CreatedOn desc")
  |> Creatio.OData.Query.top(20)
  |> Creatio.list(client)

Streaming / Auto-pagination

# Seamlessly iterates over pages of records using $top and $skip,
# with optional initial :skip offset for resuming syncs
Creatio.stream(client, "Contact", page_size: 100, skip: 500, select: ["Id", "Name"])
|> Enum.take(250)

Read-Only Safety Mode

# Protect production CRM data by enforcing client-side read-only mode
client = Creatio.new(base_url: "https://myinstance.creatio.com", read_only: true)

# Queries succeed normally:
{:ok, contacts} = Creatio.list(client, "Contact")

# All mutation attempts are blocked locally with status 403 / "ReadOnlyMode":
{:error, %Creatio.Error{code: "ReadOnlyMode"}} = Creatio.create(client, "Contact", %{"Name" => "Jane"})

Batch Operations

batch =
  Creatio.batch_new(continue_on_error: true)
  |> Creatio.Batch.add_create("Contact", %{"Name" => "John Doe"})
  |> Creatio.Batch.add_update("Contact", "some-uuid", %{"JobTitle" => "Director"})

{:ok, responses} = Creatio.batch(client, batch)

Summary

Functions

batch(client, batch_or_requests, opts \\ [])

Executes an OData batch request (POST /0/odata/$batch).

batch!(client, batch_or_requests, opts \\ [])

Same as batch/3, raising Creatio.Error on failure.

batch_new(opts \\ [])

Initializes a new Creatio.Batch request.

batch_parse_multipart(body, boundary \\ nil)

Parses a multipart/mixed batch response body.

batch_query(client, query_payload, opts \\ [])

Executes a BatchQuery against /0/DataService/json/SyncReply/BatchQuery.

batch_query!(client, query_payload, opts \\ [])

Same as batch_query/3, raising Creatio.Error on failure.

batch_to_multipart(batch, opts \\ [])

Serializes a batch to a multipart/mixed MIME body string. Returns {boundary, body}.

count(client, entity, opts \\ [])

Gets total count of an entity collection (GET /0/odata/{Entity}/$count).

count!(client, entity, opts \\ [])

Same as count/3, raising Creatio.Error on failure.

create(client, entity, attrs, opts \\ [])

Creates an entity record (POST /0/odata/{Entity}).

create!(client, entity, attrs, opts \\ [])

Same as create/4, raising Creatio.Error on failure.

custom_service(client, service_name, endpoint, payload \\ %{}, opts \\ [])

Calls a custom Creatio REST web service (/0/rest/{service_name}/{endpoint}).

custom_service!(client, service_name, endpoint, payload \\ %{}, opts \\ [])

Same as custom_service/5, raising Creatio.Error on failure.

data_service_query(client, action, query_payload, opts \\ [])

Executes a generic DataService query against /0/DataService/json/SyncReply/{action}.

data_service_query!(client, action, query_payload, opts \\ [])

Same as data_service_query/4, raising Creatio.Error on failure.

delete(client, entity, id, opts \\ [])

Deletes an entity record (DELETE /0/odata/{Entity}({id})).

delete!(client, entity, id, opts \\ [])

Same as delete/4, raising Creatio.Error on failure.

delete_field(client, entity, id, field_name, opts \\ [])

Deletes a specific field value (DELETE /0/odata/{Entity}({id})/{Field}).

delete_field!(client, entity, id, field_name, opts \\ [])

Same as delete_field/5, raising Creatio.Error on failure.

delete_query(client, query_payload, opts \\ [])

Executes a DeleteQuery against /0/DataService/json/SyncReply/DeleteQuery.

delete_query!(client, query_payload, opts \\ [])

Same as delete_query/3, raising Creatio.Error on failure.

execute(query_or_entity, client, opts \\ [])

Executes an OData query or entity listing. Alias for list/3.

execute!(query_or_entity, client, opts \\ [])

Same as execute/3, raising Creatio.Error on failure.

from_req(req, opts \\ [])

Builds a Creatio.Client from an existing Req.Request.

get(client, entity, id, opts \\ [])

Retrieves a single entity by its primary ID (GET /0/odata/{Entity}({id})).

get!(client, entity, id, opts \\ [])

Same as get/4, raising Creatio.Error on failure.

get_field(client, entity, id, field_name, opts \\ [])

Retrieves a specific field value by ID (GET /0/odata/{Entity}({id})/{Field}).

get_field!(client, entity, id, field_name, opts \\ [])

Same as get_field/5, raising Creatio.Error on failure.

get_field_value(client, entity, id, field_name)

Retrieves raw scalar/stream value (GET /0/odata/{Entity}({id})/{Field}/$value).

get_field_value!(client, entity, id, field_name)

Same as get_field_value/4, raising Creatio.Error on failure.

get_navigation(client, entity, id, nav_property, opts \\ [])

Retrieves related records via a navigation property (GET /0/odata/{Entity}({id})/{Property}).

get_navigation!(client, entity, id, nav_property, opts \\ [])

Same as get_navigation/5, raising Creatio.Error on failure.

insert_query(client, query_payload, opts \\ [])

Executes an InsertQuery against /0/DataService/json/SyncReply/InsertQuery.

insert_query!(client, query_payload, opts \\ [])

Same as insert_query/3, raising Creatio.Error on failure.

list(query_or_entity, client, opts \\ [])

Queries an entity collection (GET /0/odata/{Entity}).

list!(query_or_entity, client, opts \\ [])

Same as list/3, raising Creatio.Error on failure.

login(client_or_req, username, password, opts \\ [])

Authenticates via Forms authentication using username and password.

login_oauth(client, opts \\ [])

Authenticates via OAuth 2.0 client credentials against the Identity Service.

new(opts \\ [])

Builds a new Creatio.Client.

oauth_health_check(client, opts \\ [])

Checks OAuth health endpoint (/0/api/OAuthHealthCheck).

odata3_count(client, entity, opts \\ [])

Gets total count of an entity collection in OData 3.

odata3_count!(client, entity, opts \\ [])

Same as odata3_count/3, raising Creatio.Error on failure.

odata3_create(client, entity, attrs, opts \\ [])

Creates an entity via legacy OData 3.

odata3_create!(client, entity, attrs, opts \\ [])

Same as odata3_create/4, raising Creatio.Error on failure.

odata3_delete(client, entity, id, opts \\ [])

Deletes an entity via legacy OData 3.

odata3_delete!(client, entity, id, opts \\ [])

Same as odata3_delete/4, raising Creatio.Error on failure.

odata3_get(client, entity, id, opts \\ [])

Retrieves an entity by ID via legacy OData 3.

odata3_get!(client, entity, id, opts \\ [])

Same as odata3_get/4, raising Creatio.Error on failure.

odata3_get_field(client, entity, id, field_name, opts \\ [])

Retrieves a field value of an entity in OData 3.

odata3_get_field!(client, entity, id, field_name, opts \\ [])

Same as odata3_get_field/5, raising Creatio.Error on failure.

odata3_get_field_value(client, entity, id, field_name)

Retrieves raw scalar/stream value in OData 3.

odata3_get_field_value!(client, entity, id, field_name)

Same as odata3_get_field_value/4, raising Creatio.Error on failure.

odata3_get_navigation(client, entity, id, nav_property, opts \\ [])

Retrieves related records via a navigation property in OData 3.

odata3_get_navigation!(client, entity, id, nav_property, opts \\ [])

Same as odata3_get_navigation/5, raising Creatio.Error on failure.

odata3_list(query_or_entity, client, opts \\ [])

Queries an entity collection via legacy OData 3 (/0/ServiceModel/EntityDataService.svc/).

odata3_list!(query_or_entity, client, opts \\ [])

Same as odata3_list/3, raising Creatio.Error on failure.

odata3_stream(query_or_entity, client, opts \\ [])

Returns a lazy Stream that paginates through records of a legacy OData 3 entity collection.

odata3_stream!(query_or_entity, client, opts \\ [])

Same as odata3_stream/3.

odata3_update(client, entity, id, attrs, opts \\ [])

Updates an entity via legacy OData 3.

odata3_update!(client, entity, id, attrs, opts \\ [])

Same as odata3_update/5, raising Creatio.Error on failure.

openid_configuration(url_or_client, opts \\ [])

Retrieves OpenID configuration (/.well-known/openid-configuration).

query(entity)

Initializes a new Creatio.OData.Query builder.

select_query(client, query_payload, opts \\ [])

Executes a SelectQuery against /0/DataService/json/SyncReply/SelectQuery.

select_query!(client, query_payload, opts \\ [])

Same as select_query/3, raising Creatio.Error on failure.

stream(query_or_entity, client, opts \\ [])

Returns a lazy Stream that paginates through records of an entity or query.

update(client, entity, id, attrs, opts \\ [])

Updates an entity record (PATCH /0/odata/{Entity}({id})).

update!(client, entity, id, attrs, opts \\ [])

Same as update/5, raising Creatio.Error on failure.

update_field(client, entity, id, field_name, value, opts \\ [])

Updates a field or octet-stream binary (PUT /0/odata/{Entity}({id})/{Field}).

update_field!(client, entity, id, field_name, value, opts \\ [])

Same as update_field/6, raising Creatio.Error on failure.

update_query(client, query_payload, opts \\ [])

Executes an UpdateQuery against /0/DataService/json/SyncReply/UpdateQuery.

update_query!(client, query_payload, opts \\ [])

Same as update_query/3, raising Creatio.Error on failure.

Functions

batch(client, batch_or_requests, opts \\ [])

Executes an OData batch request (POST /0/odata/$batch).

batch!(client, batch_or_requests, opts \\ [])

Same as batch/3, raising Creatio.Error on failure.

batch_new(opts \\ [])

Initializes a new Creatio.Batch request.

batch_parse_multipart(body, boundary \\ nil)

Parses a multipart/mixed batch response body.

batch_query(client, query_payload, opts \\ [])

Executes a BatchQuery against /0/DataService/json/SyncReply/BatchQuery.

batch_query!(client, query_payload, opts \\ [])

Same as batch_query/3, raising Creatio.Error on failure.

batch_to_multipart(batch, opts \\ [])

Serializes a batch to a multipart/mixed MIME body string. Returns {boundary, body}.

count(client, entity, opts \\ [])

Gets total count of an entity collection (GET /0/odata/{Entity}/$count).

count!(client, entity, opts \\ [])

Same as count/3, raising Creatio.Error on failure.

create(client, entity, attrs, opts \\ [])

Creates an entity record (POST /0/odata/{Entity}).

create!(client, entity, attrs, opts \\ [])

Same as create/4, raising Creatio.Error on failure.

custom_service(client, service_name, endpoint, payload \\ %{}, opts \\ [])

Calls a custom Creatio REST web service (/0/rest/{service_name}/{endpoint}).

custom_service!(client, service_name, endpoint, payload \\ %{}, opts \\ [])

Same as custom_service/5, raising Creatio.Error on failure.

data_service_query(client, action, query_payload, opts \\ [])

Executes a generic DataService query against /0/DataService/json/SyncReply/{action}.

data_service_query!(client, action, query_payload, opts \\ [])

Same as data_service_query/4, raising Creatio.Error on failure.

delete(client, entity, id, opts \\ [])

Deletes an entity record (DELETE /0/odata/{Entity}({id})).

delete!(client, entity, id, opts \\ [])

Same as delete/4, raising Creatio.Error on failure.

delete_field(client, entity, id, field_name, opts \\ [])

Deletes a specific field value (DELETE /0/odata/{Entity}({id})/{Field}).

delete_field!(client, entity, id, field_name, opts \\ [])

Same as delete_field/5, raising Creatio.Error on failure.

delete_query(client, query_payload, opts \\ [])

Executes a DeleteQuery against /0/DataService/json/SyncReply/DeleteQuery.

delete_query!(client, query_payload, opts \\ [])

Same as delete_query/3, raising Creatio.Error on failure.

execute(query_or_entity, client, opts \\ [])

Executes an OData query or entity listing. Alias for list/3.

execute!(query_or_entity, client, opts \\ [])

Same as execute/3, raising Creatio.Error on failure.

from_req(req, opts \\ [])

Builds a Creatio.Client from an existing Req.Request.

get(client, entity, id, opts \\ [])

Retrieves a single entity by its primary ID (GET /0/odata/{Entity}({id})).

get!(client, entity, id, opts \\ [])

Same as get/4, raising Creatio.Error on failure.

get_field(client, entity, id, field_name, opts \\ [])

Retrieves a specific field value by ID (GET /0/odata/{Entity}({id})/{Field}).

get_field!(client, entity, id, field_name, opts \\ [])

Same as get_field/5, raising Creatio.Error on failure.

get_field_value(client, entity, id, field_name)

Retrieves raw scalar/stream value (GET /0/odata/{Entity}({id})/{Field}/$value).

get_field_value!(client, entity, id, field_name)

Same as get_field_value/4, raising Creatio.Error on failure.

get_navigation(client, entity, id, nav_property, opts \\ [])

Retrieves related records via a navigation property (GET /0/odata/{Entity}({id})/{Property}).

get_navigation!(client, entity, id, nav_property, opts \\ [])

Same as get_navigation/5, raising Creatio.Error on failure.

insert_query(client, query_payload, opts \\ [])

Executes an InsertQuery against /0/DataService/json/SyncReply/InsertQuery.

insert_query!(client, query_payload, opts \\ [])

Same as insert_query/3, raising Creatio.Error on failure.

list(query_or_entity, client, opts \\ [])

Queries an entity collection (GET /0/odata/{Entity}).

list!(query_or_entity, client, opts \\ [])

Same as list/3, raising Creatio.Error on failure.

login(client_or_req, username, password, opts \\ [])

Authenticates via Forms authentication using username and password.

login_oauth(client, opts \\ [])

Authenticates via OAuth 2.0 client credentials against the Identity Service.

new(opts \\ [])

Builds a new Creatio.Client.

Options

  • :base_url - The base URL of the Creatio instance (e.g. "https://myinstance.creatio.com").
  • :auth_token - OAuth 2.0 Bearer access token.
  • :cookie - Cookie string for Forms authentication.
  • :bpmcsrf - CSRF token string for Forms authentication.
  • :identity_service_url - Base URL for Creatio Identity Service.
  • :client_id - OAuth 2.0 client ID.
  • :client_secret - OAuth 2.0 client secret.
  • :read_only - If true, enables defense-in-depth read-only mode to prevent mutation requests (defaults to false, or Application.get_env(:creatio, :read_only), or CREATIO_READ_ONLY env var).
  • :req_options - Extra options passed directly to Req.new/1.

oauth_health_check(client, opts \\ [])

Checks OAuth health endpoint (/0/api/OAuthHealthCheck).

odata3_count(client, entity, opts \\ [])

Gets total count of an entity collection in OData 3.

odata3_count!(client, entity, opts \\ [])

Same as odata3_count/3, raising Creatio.Error on failure.

odata3_create(client, entity, attrs, opts \\ [])

Creates an entity via legacy OData 3.

odata3_create!(client, entity, attrs, opts \\ [])

Same as odata3_create/4, raising Creatio.Error on failure.

odata3_delete(client, entity, id, opts \\ [])

Deletes an entity via legacy OData 3.

odata3_delete!(client, entity, id, opts \\ [])

Same as odata3_delete/4, raising Creatio.Error on failure.

odata3_get(client, entity, id, opts \\ [])

Retrieves an entity by ID via legacy OData 3.

odata3_get!(client, entity, id, opts \\ [])

Same as odata3_get/4, raising Creatio.Error on failure.

odata3_get_field(client, entity, id, field_name, opts \\ [])

Retrieves a field value of an entity in OData 3.

odata3_get_field!(client, entity, id, field_name, opts \\ [])

Same as odata3_get_field/5, raising Creatio.Error on failure.

odata3_get_field_value(client, entity, id, field_name)

Retrieves raw scalar/stream value in OData 3.

odata3_get_field_value!(client, entity, id, field_name)

Same as odata3_get_field_value/4, raising Creatio.Error on failure.

odata3_get_navigation(client, entity, id, nav_property, opts \\ [])

Retrieves related records via a navigation property in OData 3.

odata3_get_navigation!(client, entity, id, nav_property, opts \\ [])

Same as odata3_get_navigation/5, raising Creatio.Error on failure.

odata3_list(query_or_entity, client, opts \\ [])

Queries an entity collection via legacy OData 3 (/0/ServiceModel/EntityDataService.svc/).

odata3_list!(query_or_entity, client, opts \\ [])

Same as odata3_list/3, raising Creatio.Error on failure.

odata3_stream(query_or_entity, client, opts \\ [])

Returns a lazy Stream that paginates through records of a legacy OData 3 entity collection.

Options

  • :page_size - Records per request (default: 100).
  • :skip - Initial offset to begin streaming from (default: 0).
  • :select - List or string of fields to retrieve.
  • :filter - Filter expression.
  • :orderby - Ordering expression.
  • :expand - Relations to expand.

odata3_stream!(query_or_entity, client, opts \\ [])

Same as odata3_stream/3.

odata3_update(client, entity, id, attrs, opts \\ [])

Updates an entity via legacy OData 3.

odata3_update!(client, entity, id, attrs, opts \\ [])

Same as odata3_update/5, raising Creatio.Error on failure.

openid_configuration(url_or_client, opts \\ [])

Retrieves OpenID configuration (/.well-known/openid-configuration).

query(entity)

Initializes a new Creatio.OData.Query builder.

select_query(client, query_payload, opts \\ [])

Executes a SelectQuery against /0/DataService/json/SyncReply/SelectQuery.

select_query!(client, query_payload, opts \\ [])

Same as select_query/3, raising Creatio.Error on failure.

stream(query_or_entity, client, opts \\ [])

Returns a lazy Stream that paginates through records of an entity or query.

Options

  • :page_size - Number of records per request (default: 100).
  • :skip - Initial offset to begin streaming from (default: 0).
  • :select - List of fields or comma-separated string to retrieve.
  • :filter - OData filter expression string.
  • :orderby - Ordering expression string.
  • :expand - Relations to expand.

update(client, entity, id, attrs, opts \\ [])

Updates an entity record (PATCH /0/odata/{Entity}({id})).

update!(client, entity, id, attrs, opts \\ [])

Same as update/5, raising Creatio.Error on failure.

update_field(client, entity, id, field_name, value, opts \\ [])

Updates a field or octet-stream binary (PUT /0/odata/{Entity}({id})/{Field}).

update_field!(client, entity, id, field_name, value, opts \\ [])

Same as update_field/6, raising Creatio.Error on failure.

update_query(client, query_payload, opts \\ [])

Executes an UpdateQuery against /0/DataService/json/SyncReply/UpdateQuery.

update_query!(client, query_payload, opts \\ [])

Same as update_query/3, raising Creatio.Error on failure.