Difference between revisions of "CRM-2 Activities API"

From Opentaps Wiki
Jump to navigationJump to search
(New page: == Activities API allows to perform operations on activities. == The API calls should be prefixed with URL <tt>http://crm-2-url/activities</tt>. Available operations are: === GET: Retri...)
 
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
== Activities API allows to perform operations on activities. ==
+
== Activities API ==
  
−
The API calls should be prefixed with URL <tt>http://crm-2-url/activities</tt>.
+
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 <tt>https://crm2.opentaps.com/activities</tt>.
  
 
Available operations are:
 
Available operations are:
Line 7: Line 9:
 
=== GET: Retrieve activities ===
 
=== GET: Retrieve activities ===
 
Use pattern /{numberOfActivities}/{startFrom}
 
Use pattern /{numberOfActivities}/{startFrom}
 +
 +
Attributes:
 
* numberOfActivities - number of activities to return.
 
* numberOfActivities - number of activities to return.
−
* startFrom(optional) - return activities skipping specified number of items. W/o this attribute service returns all activites.
+
* 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 ===
 
=== DELETE: Delete an activity ===
 
Use pattern /{activityId}
 
Use pattern /{activityId}
 +
 +
Attributes:
 
* activityId - An activity identifier.
 
* activityId - An activity identifier.
 +
 +
Parameters:
 +
* authToken - OAuth access token.
  
 
=== POST: Create or update activity ===
 
=== POST: Create or update activity ===
 
There is no special pattern. Post request to /activities.
 
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. ===
 
=== POST: Associate a contact with an activity in a role. ===
 
Use pattern /contact/add
 
Use pattern /contact/add
−
Required parameters:
 
  
 +
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.
+
=== POST: Remove contact association. ===
 
Use pattern /contact/remove
 
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

Latest revision as of 23:21, 11 March 2014

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
Retrieved from "https://docs.opentaps.org/docs/index.php?title=CRM-2_Activities_API&oldid=7458"