Difference between revisions of "CRM-2 Administrative API"

From Opentaps Wiki
Jump to navigationJump to search
(→‎Emails To Poll)
(→‎Email Notifications)
 
(28 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
Administrative API is used to manage your domain.  The API calls follow the general RESTful pattern of [[CRM-2 API]].  The base URL is <tt>http://crm-2-url/admin/</tt>
+
Administrative API is used to manage your domain.   
  
−
To access the admin API, your user must '''DOMAIN_CONF''' permission.
+
The API calls follow the general RESTful pattern of [[CRM-2 API]].  The base URL is <tt>https://crm2.opentaps.com/admin/</tt>
 +
 
 +
To access the admin API, your user must have the '''DOMAIN_CONF''' permission.
 +
 
 +
For all requests the clientDomain and authToken parameters are required.
  
 
Here are the additional resources available:
 
Here are the additional resources available:
 +
 +
=== Reset (Permanent) Token ===
 +
 +
Method: POST
 +
URL extension: <tt>/admin/reset-token</tt>
 +
Parameter:
 +
* Current permanent auth token for your user
 +
* Client domain
 +
 +
This API expires (deletes) the current permanent auth token, generates a new one, and returns it to you as the result.  After this, you must use the new one to access the system.  The API will validate that the token you've supplied is for a user of your domain.
 +
 +
=== Users ===
 +
 +
Add or remove users for a Contact
 +
 +
URL extension: <tt>/admin/user</tt>
 +
 +
Parameters:
 +
* contactId : unique ID of your Contact
 +
* userId: id of user.  For Gmail, use full email (someone@gmail.com).  For twitter, use username without the initial @ (someone)
 +
* userIdType: type of your user id.  Use GOOGLE_APPS for Gmail or TWITTER_LOGIN for Twitter.
 +
 +
Add a new User and Contact at the same time with
 +
 +
URL extension: <tt>/admin/user-contact</tt>
 +
 +
Parameters:
 +
* firstName
 +
* lastName
 +
* companyName
 +
* emailAddress
 +
* userId
 +
* userIdType: Same as above
 +
 +
=== User Permissions ===
 +
 +
Add or remove a security permission from a user
 +
 +
URL extension: <tt>/admin/user-permission</tt>
 +
 +
Parameters:
 +
* userId: unique id of the user
 +
* permission: Permission string
 +
 +
If the permission you are trying to add is not a valid permission, you will get an error message with a list of the valid permissions.
 +
 +
Valid permissions are:
 +
* CONTACT_VIEW - view contacts and contact groups
 +
* CONTACT_UPDATE - create, update, delete contacts and contact groups
 +
* ACTIVITY_VIEW - view activities, such as tasks
 +
* ACTIVITY_UPDATE - create, update, delete activities
 +
* DOMAIN_CONF - administer the domain.
 +
 +
=== Email Notifications ===
 +
 +
Configure the email account to use when sending notification emails for your domain.  You must also configure the same email as an email to poll (see below) separately so that the responses are also registered.  Otherwise, response to your notification emails will be ignored.
 +
 +
URL extension: <tt>/admin/email-notifications</tt> (ie, <tt>https://crm2.opentaps.com/admin/email-notifications</tt>)
 +
 +
Parameters are the ones for your mail server, ie <tt>mailUser</tt>, <tt>mailPass</tt>, <tt>mailStoreProtocol</tt>, <tt>mailHost</tt>.  For gmail, use <tt>smtp</tt> and <tt>smtp.gmail.com</tt> for protocol and host. Note: do not try to use smtps which is not a valid transport, the code will connect using SSL on port 465 automatically.
 +
 +
For all requests the clientDomain and authToken parameters are required.
 +
 +
* The method POST and PUT is used to SET the email notification account settings.
 +
* The method DELETE is used to REMOVE the email notification account settings.
 +
* The method GET is used to GET the current email notification account settings.
 +
 +
Note: the password is encrypted in the DB and won't be returned in the replies.
  
 
=== Emails To Poll ===
 
=== Emails To Poll ===
Line 9: Line 81:
 
Configures the emails to be polled for your domain.   
 
Configures the emails to be polled for your domain.   
  
−
URL extension: <tt>email-to-poll</tt> (ie, <tt>http://crm-2-url/admin/email-to-poll</tt>)
+
URL extension: <tt>/admin/email-to-poll</tt> (ie, <tt>https://crm2.opentaps.com/admin/email-to-poll</tt>)
 +
 
 +
Parameters are the ones for your mail server, ie <tt>mailUser</tt>, <tt>mailPass</tt>, <tt>mailStoreProtocol</tt>, <tt>mailHost</tt>.  For gmail, use <tt>gimap</tt> and <tt>pop.googlemail.com</tt> for protocol and host.
 +
 
 +
* The method POST is used to ADD email to poll.
 +
* The method PUT is used to UPDATE email to poll.
 +
* The method DELETE is used to REMOVE email to poll.
 +
* The method GET is used to GET list of the emails to poll.
 +
 
 +
For POST, PUT and DELETE, mailUser is required.
 +
 
 +
Note: the password is encrypted in the DB and won't be returned in the replies.
  
−
==== POST ====
+
=== Valid Activity Types ===
  
−
Add new email to poll with parameters:
+
Configures the valid activity types for your domain's application settings.  Activity types are always capitalized and automatically capitalized when you add them.
−
* mailUser
 
−
* mailPass
 
−
* mailStoreProtocol
 
−
* mailHost
 
  
−
For gmail, use <tt>imaps</tt> and <tt>pop.google.com</tt> for protocol and host.
+
URL: <tt>https://crm2.opentaps.com/admin/activity-type</tt>
  
−
==== PUT ====
+
* POST adds a single activityType
 +
* GET returns a list of valid activity types
 +
* DELETE removes a single activityType
  
−
Updates an email to poll:
+
=== Twitter ===
−
* '''mailUser''' - identifies the email to update
 
  
−
Other parameters are same as for POST operation and will be updated for your email.
+
Configures the twitter users which opentaps CRM2 uses to interact with twitter.  Normally this is done automatically when somebody logs into twitter.com once from the login page, but you can control it more explicitly using this API to add a user or remove one that you don't want to use.
  
−
==== DELETE ====
+
URL: <tt>https://crm2.opentaps.com/admin/twitter</tt>
  
−
Removes an email from polling list:
+
* POST adds a new user to use with twitter.  Parameters are <tt>userName</tt>, <tt>userId</tt>, <tt>token</tt>, and <tt>tokenSecret</tt>
−
* '''mailUser''' - email to be removed
+
* GET returns a list of users to use with twitter
 +
* DELETE removes a user.  Parameter is <tt>userName</tt>

Latest revision as of 06:36, 15 October 2014

Administrative API is used to manage your domain.

The API calls follow the general RESTful pattern of CRM-2 API. The base URL is https://crm2.opentaps.com/admin/

To access the admin API, your user must have the DOMAIN_CONF permission.

For all requests the clientDomain and authToken parameters are required.

Here are the additional resources available:

Reset (Permanent) Token

Method: POST URL extension: /admin/reset-token Parameter:

  • Current permanent auth token for your user
  • Client domain

This API expires (deletes) the current permanent auth token, generates a new one, and returns it to you as the result. After this, you must use the new one to access the system. The API will validate that the token you've supplied is for a user of your domain.

Users

Add or remove users for a Contact

URL extension: /admin/user

Parameters:

  • contactId : unique ID of your Contact
  • userId: id of user. For Gmail, use full email (someone@gmail.com). For twitter, use username without the initial @ (someone)
  • userIdType: type of your user id. Use GOOGLE_APPS for Gmail or TWITTER_LOGIN for Twitter.

Add a new User and Contact at the same time with

URL extension: /admin/user-contact

Parameters:

  • firstName
  • lastName
  • companyName
  • emailAddress
  • userId
  • userIdType: Same as above

User Permissions

Add or remove a security permission from a user

URL extension: /admin/user-permission

Parameters:

  • userId: unique id of the user
  • permission: Permission string

If the permission you are trying to add is not a valid permission, you will get an error message with a list of the valid permissions.

Valid permissions are: 

* CONTACT_VIEW - view contacts and contact groups
* CONTACT_UPDATE - create, update, delete contacts and contact groups
* ACTIVITY_VIEW - view activities, such as tasks
* ACTIVITY_UPDATE - create, update, delete activities
* DOMAIN_CONF - administer the domain.

Email Notifications

Configure the email account to use when sending notification emails for your domain. You must also configure the same email as an email to poll (see below) separately so that the responses are also registered. Otherwise, response to your notification emails will be ignored.

URL extension: /admin/email-notifications (ie, https://crm2.opentaps.com/admin/email-notifications)

Parameters are the ones for your mail server, ie mailUser, mailPass, mailStoreProtocol, mailHost. For gmail, use smtp and smtp.gmail.com for protocol and host. Note: do not try to use smtps which is not a valid transport, the code will connect using SSL on port 465 automatically.

For all requests the clientDomain and authToken parameters are required.

  • The method POST and PUT is used to SET the email notification account settings.
  • The method DELETE is used to REMOVE the email notification account settings.
  • The method GET is used to GET the current email notification account settings.

Note: the password is encrypted in the DB and won't be returned in the replies.

Emails To Poll

Configures the emails to be polled for your domain.

URL extension: /admin/email-to-poll (ie, https://crm2.opentaps.com/admin/email-to-poll)

Parameters are the ones for your mail server, ie mailUser, mailPass, mailStoreProtocol, mailHost. For gmail, use gimap and pop.googlemail.com for protocol and host.

  • The method POST is used to ADD email to poll.
  • The method PUT is used to UPDATE email to poll.
  • The method DELETE is used to REMOVE email to poll.
  • The method GET is used to GET list of the emails to poll.

For POST, PUT and DELETE, mailUser is required.

Note: the password is encrypted in the DB and won't be returned in the replies.

Valid Activity Types

Configures the valid activity types for your domain's application settings. Activity types are always capitalized and automatically capitalized when you add them.

URL: https://crm2.opentaps.com/admin/activity-type

  • POST adds a single activityType
  • GET returns a list of valid activity types
  • DELETE removes a single activityType

Twitter

Configures the twitter users which opentaps CRM2 uses to interact with twitter. Normally this is done automatically when somebody logs into twitter.com once from the login page, but you can control it more explicitly using this API to add a user or remove one that you don't want to use.

URL: https://crm2.opentaps.com/admin/twitter

  • POST adds a new user to use with twitter. Parameters are userName, userId, token, and tokenSecret
  • GET returns a list of users to use with twitter
  • DELETE removes a user. Parameter is userName
Retrieved from "https://docs.opentaps.org/docs/index.php?title=CRM-2_Administrative_API&oldid=7555"