Skip to content

Campaign Manipulation

Jump to bottom
Steve Nolen edited this page Mar 4, 2016 · 16 revisions

Campaign Create

What does it do?

Creates campaigns.

URI

campaign/create

Access Rules

Only users with their campaign creation privilege set to true can create campaigns. Once a campaign is created, the user becomes an author of the campaign.

Input Parameters

  • (r) auth_token = A valid authentication token.
  • (r) client = A short description of the client making the request.
  • (r) running_state = Initial running state.
  • (r) privacy_state = Initial privacy state.
  • (r) class_urn_list = A comma-separated list of classes that already exist in the system and that the currently logged in user is a member of.
  • (r) xml = An XML file that defines the campaign.
  • (o) description = A description of the campaign.
  • (o) campaign_urn = The URN for this new campaign. This may be a parameter instead of in the XML, but if it is in both places it must match exactly.
  • (o) campaign_name = The name for this new campaign. This may be a parameter instead of in the XML, but if it is in both places it must match exactly.
  • (o) editable = Initial editable state (true/false). Defaults to false for backwards compatibility with the 2.x codebase.

Example POST

POST /app/campaign/create HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 Set-Cookie: auth_token=dff783ce-cf1a-4cc8-b750-dee774a82e6f

  running_state=running
  &client=kermit
  &privacy_state=shared
  &description=Some%20description
  &classes=urn:class:pigs_in_space,urn:another:class
  &xml=xmlFile_withType"text/xml"

cURL Example

curl -v -F "auth_token=aa063533-34fe-47ae-b9d2-ada11647d11e" -F "running_state=stopped" -F "privacy_state=private" -F "description=Test description" -F "class_urn_list=urn:campaign:ucla:adhd" -F "xml=@/adhd.xml;type=text/xml" http://localhost:8080/app/campaign/create

Output Format

Success

{
    "result":"success",
}

Failure

See the error page for a description of error codes and their associated descriptions.

↑ Back to Top

Campaign Read

What does it do?

Reads campaigns.

URI

campaign/read

Access Rules

Any user that has been associated with a campaign can read a campaign. A user becomes associated with a campaign when a class containing the user is added to the campaign.

Input Parameters

  • (r) auth_token = A valid authentication token. May also be set using the Set-Cookie header.
  • (r) client = A short description of the client making the request.
  • (r) output_format = short || long || xml
  • (o) campaign_urn_list = urn:campaign:CS101,urn:campaign:CS102
  • (o) start_date = 2011-11-01
  • (o) end_date = 2011-11-11
  • (o) privacy_state = shared || private
  • (o) running_state = running || stopped
  • (o) user_role = author (used as a filter on the logged-in user)
  • (o) class_urn_list = urn:class:class1,urn:class:class2
  • (o) campaign_name_search = A whitespace-deliminated, double-quote-respected, search string which limits the results to only those campaigns whose name contains at least one of the search tokens.
  • (o) campaign_description_search = A whitespace-deliminated, double-quote-respected, search string which limits the results to only those campaigns that have a description and whose description contains at least one of the search tokens.

Example POST

POST /app/campaign/read HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 Set-Cookie: auth_token=dff783ce-cf1a-4cc8-b750-dee774a82e6f

  running_state=running
  &client=ohmage-js
  &privacy_state=shared
  &description=Some%20description
  &classes=urn:class:pigs_in_space,urn:another:class
  &xml=xmlFile_withType"text/xml"

cURL Example

curl -v -d "auth_token=119d957f-972e-4d22-a41a-c2728cc65f49&client=curl&output_format=short" http://localhost:8080/app/campaign/read

Output Format

Success -- short output_format

{
    "result" : "success",
    "metadata" : {
        "number_of_results": 2, 
        "items" : [
            "urn:campaign1", 
            "urn:campaign2"
        ]
    },
    "data": 
    {
        "urn:campaign1": {
            "name":"campaign1",
            "icon_url":http://some.domain/path/to/icon.extension",
            "authored_by":"The name of the entity, not necessarily the user, that authored or owns this campaign.",
            "running_state" : "running",
            "privacy_state" : "shared",
            "creation_timestamp":"2010-04-20 20:08:21",
            "user_roles" : ["author", "participant", "analyst"],
            "description" : "Awesome campaign!"
            "classes":["urn:class:CS101", "urn:class:CS202",...]
        },
        "urn:campaign2": {
            "name":"campaign2",
            "running_state" : "inactive",
            "privacy_state" : "private",
            "creation_timestamp":"2010-03-20 20:08:21",
            "user_roles" : ["author"],
            "description" : "Lame campaign o.O"
            "classes":["urn:class:CS101", "urn:class:CS202",...]
        }
    }
}

Success -- long output_format

{
    "result":"success", 
    "metadata": {
        "number_of_results": 2, 
        "items" : [
            "urn:campaign:campaign1", 
            "urn:campaign:campaign2"
        ]
    }
    "data":[ {
        "urn:campaign:campaign1": {
            "name":"CHIPTS",
            "creation_timestamp":"2010-04-20 20:08:21.634121"
            "description":"monitoring sleep patterns",
            "icon_url":"http://some.domain/path/to/icon.extension",
            "authored_by":"The name of the entity, not necessarily the user, that authored or owns this campaign.",
            "running_state":"running",
            "privacy_state":"public",
            "user_roles":["author", "participant", "analyst"]
            "classes":["urn:class:CS101", "urn:class:CS202",...]
            "user_role_campaign":{ 
                "author":["Bob","Jane","Bill"], 
                "supervisor":["Miss.Jones"],
                "participant":["Bob","Jane","Anna"],
                "analyst":["Bob","Joe","Mike"]
            },
           "xml": "<XML Configuration>",
       },
       "urn:campaign:campaign2": {
           ...
       }, 
      ...
     ]
 }

Success -- xml output_format

<The contents of the XML.>

Failure

See the error page for a description of error codes and their associated descriptions.

↑ Back to Top

Campaign Search

What does it do?

This API is intended for administrators to view any information about any of the campaigns in the system. If all of the optional parameters are missing, then all of the information about all of the campaigns in the system is returned. With great power comes great responsibility.

URI

campaign/search

Access Rules

Admin access only.

Input Parameters

  • (r) auth_token = A valid authentication token. May also be set using the Set-Cookie header.
  • (r) client = ohmage-gwt
  • (o) campaign_urn = A partial campaign URN to limit the results to only those campaigns whose URN contain this value.
  • (o) campaign_name = A partial campaign name to limit the results to only those campaigns whose name contains this value.
  • (o) description = A partial campaign description to limit the results to only those campaigns whose description contains this value.
  • (o) xml = A partial XML to limit the results to only those campaigns whose XML contains this value.
  • (o) authored_by = A partial authored by value to limit the results to only those campaigns that contain an authored by value and whose value contains this value.
  • (o) start_date = An ISO 8601-formatted date to limit the results to campaigns that were created on or after this date.
  • (o) end_date = An ISO 8601-formatted date to limit the results to campaigns that were created on or before this date.
  • (o) privacy_state = A campaign privacy state limiting the results to campaigns that have this privacy state.
  • (o) running_state = A campaign running state limiting the results to campaigns that have this running state.

Example POST

POST /app/campaign/search HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 Set-Cookie: auth_token=dff783ce-cf1a-4cc8-b750-dee774a82e6f

  running_state=running
  &client=ohmage-gwt
  &privacy_state=shared
  &description=Some%20description
  &classes=urn:class:pigs_in_space,urn:another:class
  &xml=xmlFile_withType"text/xml"

cURL Example

curl -v -d "auth_token=119d957f-972e-4d22-a41a-c2728cc65f49&client=curl" http://localhost:8080/app/campaign/search

Output Format

Success

{
    "result" : "success",
    "data" : {
        "urn:campaign1": {
        "name" : "campaign1",
        "description" : "Awesome campaign!",
        "xml" : "<The campaign's XML>",
        "creation_timestamp":"2010-04-20 20:08:21",
        "running_state" : "running",
        "privacy_state" : "shared",
        "user_role_camaign" : {
        "participant" : [
            "user1",
            "user2"
         ],
         "analyst" : [
             "user1",
             "user3"
         ],
         "author" : [
             "user2"
         ],
         "supervisor" : [
             "user2",
             "user4
         ]
     },
     "classes" : [
         "urn:class:one",
          "urn:class:two"
     ]
     "icon_url":"http://some.domain/path/to/icon.extension",
     "authored_by":"The name of the entity, not necessarily the user, that authored or owns this campaign."
 },
 "urn:campaign2": {
     ...
}

Failure

See the error page for a description of error codes and their associated descriptions.

↑ Back to Top

Campaign Update

What does it do?

Updates campaigns.

URI

campaign/update

Access Rules

  • A campaign supervisor or author can update a campaign's XML configuration only if there are no survey responses for the campaign.
  • A campaign supervisor or author can update a campaign's description, privacy state, or running state at any time.
  • A campaign supervisor or author can update the classes associated with a campaign at any time.
  • A campaign supervisor or author can update the participants, analysts or authors associated with a campaign at any time.
  • A campaign supervisor can update the supervisors associated with a campaign at any time.

Input Parameters

  • (r) auth_token = Token
  • (r) client = A short description of the client making the request.
  • (r) campaign_urn = URN for the campaign being modified.
  • (o) running_state = New running state.
  • (o) privacy_state = New privacy state.
  • (o) editable = New editable state.
  • (o) class_list_add = A comma-separated list of classes that already exist in the system and that the currently logged in user is a member of. Any classes that are in this list but the campaign is not current associated with will have a new association created and its members will also be associated with the campaign.
  • (o) class_list_remove = A comma-separated list of classes that already exist in the system and that the currently logged in user is a member of. Any classes that are in this list will have their associations removed and the user-campaign relationship removed as well
  • (o) xml = A new XML file that defines the campaign.
  • (o) description = A new description of the campaign.
  • (o) user_role_list_add = A list of users and roles to add to the campaign with the format user1;role1,user2;role1,user1;role2
  • (o) user_role_list_remove = A list of users and roles to remove from the campaign with the format user1;role1,user1;role2,user2;role3

Example POST

POST /app/campaign/update HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 Set-Cookie: auth_token=dff783ce-cf1a-4cc8-b750-dee774a82e6f

  running_state=running
  &client=ohmage-gwt
  &auth_token=de2c22ac-db47-47a4-8ec6-1522906061e0
  &campaign_urn=urn:some:campaign
  &running_state=running
  &privacy_state=shared
  &description=Some%20description
  &classes=urn:class:artificial_intelligence,urn:another:class
  &xml=xmlFile_withType"text/xml"

cURL Example

curl -v -F "auth_token=7488a90f-7965-4280-b70f-80a7923deab5" -F "campaign_urn=urn:campaign:ucla:chipts" -F "description=Best Campaign Ever" -F "running_state=running" -F "privacy_state=private" -F "class_urn_list=urn:class:ohmage" -F "xml=@/chipts.xml;type=text/xml" http://localhost:8080/app/campaign/update

Output Format

Success

{
    "result" : "success"
}

Failure

See the error page for a description of error codes and their associated descriptions.

↑ Back to Top

Campaign Delete

What does it do?

Deletes campaigns.

URI

campaign/delete

Access Rules

  • A campaign supervisor can delete a campaign at any time.
  • A campaign author can delete a campaign only if there a no survey responses for the campaign.

Input Parameters

  • (r) auth_token = Token
  • (r) client = A short description of the client making the request.
  • (r) campaign_urn = The URN of the campaign that is to be deleted.

Example POST

POST /app/campaign/delete HTTP/1.1
 Host: dev.ohmage.org
 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
 Content-Length: byte-length-of-content
 Content-Type: application/x-www-form-urlencoded
 
  auth_token=fb4f20c4-792e-4106-ac14-1cf82884aaf1&campaign_urn=urn:campaign:quit_smoking&client=ohmage-android

cURL Example

curl -v -d "auth_token=87605882-c734-4466-8eab-fb1d17dfe414&client=curl&campaign_urn=urn:campaign:ucla:media" http://localhost:8080/app/campaign/delete

Output Format

Success

{
    "result" : "success"
}

Failure

See the error page for a description of error codes and their associated descriptions.

↑ Back to Top

Clone this wiki locally