CRM-2 Activities API

From Opentaps Wiki
Jump to navigationJump to search

Activities API

An Activity is pretty flexible and could be anything -- a note, a tweet, an email, a task (see below.) An activity could be linked to a contact or to an external object, such as an order or quote in a legacy order management system or an invoice or payment in a legacy accounting system.

The Activities API is used for operations on Activities. The API calls should be prefixed with URL https://crm2.opentaps.com/activities.

Available operations are:

GET: Retrieve activities

Use pattern /{numberOfActivities}/{startFrom}

Attributes:

  • numberOfActivities - number of activities to return.
  • startFrom(optional) - return activities starting from specified sequence number. W/o this attribute service returns all activites.

Parameters:

  • authToken - OAuth access token.
  • clientDomain - Customer's client domain.

Return JSON.

DELETE: Delete an activity

Use pattern /{activityId}

Attributes:

  • activityId - An activity identifier.

Parameters:

  • authToken - OAuth access token.

POST: Create or update activity

There is no special pattern. Post request to /activities.

Parameters:

  • authToken - OAuth access token.
  • clientDomain - Customer's client domain.
  • Fields of activity, attributes should be prefixed with "note_field_";

POST: Associate a contact with an activity in a role.

Use pattern /contact/add

Parameters:

  • authToken - OAuth access token.
  • clientDomain - Customer's client domain.
  • activityId - An activity identifier.
  • contactId - A contact id.
  • role(optional) - A role, an arbitrary string.

POST: Remove contact association.

Use pattern /contact/remove

Parameters:

  • authToken - OAuth access token.
  • clientDomain - Customer's client domain.
  • activityId - An activity identifier.
  • contactId - A contact id.
  • role(optional) - A role, an arbitrary string.

Task API

Task is a specialized kind of Activity with a scheduled date/time and a person (Contact) that it's been assigned to. Like other activities, it also has status, notes, and activities associated with it, and some of those activities could be tasks in turn. Also like activities, it could be associated with contacts or with legacy orders/quotes/invoices/payments.

A task is uniquely identified by an activityId, just like other activities. Most operations on tasks are the same as those for activities in general and can be accessed with the activities API above, with the following exceptions at URL https://crm2.opentaps.com/task:

POST: Create a Task

Create a task by POST. In addition to the activities fields, tasks support

  • scheduledDateTime
  • assignedToContactId

Tasks do not support activityTypeId. Any task created with this POST will have activityTypeId of TASK.

GET: Search for Task

You can search for a task with the GET operation, with parameters:

  • assignedToContactId -- an Array of Contact IDs your task has been assigned to, or leave empty for any
  • fromScheduledDateTime -- if filled in, a range of date time for scheduled date/time
  • toScheduledDateTime

Task Status

A task can go through the following status:

  • Created
  • Started
  • Completed
  • Cancelled

The API doesn't restrict your updating of the status, but the normal flow would be

  • Created can be Started or Cancelled
  • Started can be Completed or Cancelled
  • Completed or Cancelled tasks cannot be changed