Difference between revisions of "CRM-2 Administrative API"

From Opentaps Wiki
Jump to navigationJump to search
(→‎Valid Activity Types)
(→‎Email Notifications)
 
(20 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
Administrative API is used to manage your domain.   
 
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>
+
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.
 
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 11: Line 81:
 
Configures the emails to be polled for your domain.   
 
Configures the emails to be polled for your domain.   
  
−
URL extension: <tt>/admin/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>imaps</tt> and <tt>pop.google.com</tt> for protocol and host.
 
  
−
For all requests the clientDomain and authToken parameters are required.
+
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 POST is used to ADD email to poll.
Line 23: Line 91:
  
 
For POST, PUT and DELETE, mailUser is required.
 
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 ===
 
=== 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 or update them.
+
Configures the valid activity types for your domain's application settings.  Activity types are always capitalized and automatically capitalized when you add them.
  
−
URL extension: <tt>/admin/activity-type</tt> (ie, <tt>http://crm-2-url/admin/activity-type</tt>)
+
URL: <tt>https://crm2.opentaps.com/admin/activity-type</tt>
  
 
* POST adds a single activityType
 
* POST adds a single activityType
 
* GET returns a list of valid activity types
 
* 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: <tt>https://crm2.opentaps.com/admin/twitter</tt>
 +
 +
* POST adds a new user to use with twitter.  Parameters are <tt>userName</tt>, <tt>userId</tt>, <tt>token</tt>, and <tt>tokenSecret</tt>
 +
* 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"