Package: mage-python-api
Mage API WrapperIntroductionThis script can be imported and used in other python scripts to simplify automated operations relying on the MAGE API.Common examples include:Creating eventsEditing event forms and observationsCopying observations from one event to anotherSetupClone the repository from GitHub.Add aconfig.pyfile to your project folder containing your credentials and MAGE server url. This file should not be uploaded to shared spaces.Copymage_api.pyso it resides alongside your other script(s).Importmage_api.pyin your python script(s) to make use of the below functionality.Installing DependenciesTo manage dependencies, this repository includes arequirements.txtfile. You can install dependencies easily via:pipinstall-rrequirements.txtFor your own projects, you should include arequirements.txtfile as well. You can generate one by:pipinstallpipreqs
pipreqs.Exampleconfig.pymage_environment='https://your-mage-url'credentials={'username':'your_mage_username','password':'your_mage_password'}Getting StartedFirst, create a session object which will be used to make all your API calls. This will log you in using the information inconfig.pyand store your own MAGE user info as theown_userattribute.importmage_api# instantiate MAGE sessionsession=mage_api.MageClient()#this is just for demonstrationprint(session.own_user)To make requests, use one of the functions documented below like this:importmage_api# instantiate MAGE sessionsession=mage_api.MageClient()# get document for event with an id of 2000my_event=session.get_event(2000)API responses are returned asformattedResponseobjects with the following attributes:response_code- indicates success or failure (Mozilla Reference)response_body- any JSON responses formatted as dictionaries, or strings (usually error messages) returnedcontent- any downloaded filesGenerally, you'll want to access theresponse_body, which will contain any information for observations or events fetched or added.importmage_api# instantiate MAGE sessionsession=mage_api.MageClient()# get document for event with an id of 2000my_event=session.get_event(2000)# get JSON response as dictionarymy_event_document=my_event.response_body# you can also use pretty_print() for more infomy_event.pretty_print()Supported MAGE OperationsThe following MAGE operations are supported with simple-to-use class functions (e.g.session.get_event()). The list isn't comprehensive at this time, but adding new functions is generally straightforward. Some operations also make use of multiple API calls (e.g.session.clone_observations()). Some functions below don't require API calls, and should be accessed directly. They are listed as such (e.g.mage_api.get_event_forms()). These usually require you to retrieve a JSON response using another function and pass the dictionary as a parameter.Authenticationlog_outlog_outLog out, use this when you're finishedParameters:NoneReturns:A string indicating successful logout.Eventsget_eventget_eventRequest document for MAGE event, including forms and other metadata.Parameters:event_id:intnumerical ID of requested eventReturns:formattedResponseobject with attributes:response_coderesponse_body(requested event document)get_eventsget_eventsRequest documents for all visible MAGE events.Parameters:populate:boolincludeteamsandlayersin event documentsReturns:formattedResponseobject with attributes:response_coderesponse_body(list of visible events)create_eventcreate_eventCreates new MAGE event and adds user (self) to that event.Parameters:name:stringname for new eventdescription:stringdescription for new eventReturns:formattedResponseobject with attributes:response_coderesponse_body(created event document)get_event_formsget_event_formsExtracts list of forms from already retrieved event document.Parameters:event_document:dictevent document fetchedReturns:A list of form documents as dictionaries.get_event_teamget_event_teamExtract team ID from already retrieved event document (does not make API call).Parameters:event_document:dictevent document fetchedReturns:Team id as anint.Observationsget_observationsget_observationsGets all observations meeting specified criteria from specified event.Parameters:event_id:intnumerical id of eventstart_date:strfilter for observations created after this date/timeend_date:strfilter for observations created before this date/timeobservation_start_date:strfilter for observations with timestamps after this date/timeobservation_end_date:strfilter for observations with timestamps before this date/timestates:strfilter for onlyactiveorarchiveobservationsReturns:formattedResponseobject with attributes:response_coderesponse_body(list of requested observation documents)create_observationcreate_observationCreates new observation using provided dictionary and event id.Parameters:observation:dictdictionary corresponding to valid observation object (format depends on event and forms)event_id:intnumerical id for destination eventReturns:formattedResponseobject with attributes:response_coderesponse_body(created observation document)clone_event_observationsclone_event_observationsCreates copies of observations from one event in another, including forms and attachments.Steps:Copies forms to event (overwrites existing forms of same name)Gets specified observations from first eventCopies observations to second event, downloading and re-uploading attachments as neededParameters:origin_event_id:intnumerical id for event you wish to copy observations FROMtarget_event_id:intnumerical id for event you wish to copy observations TOstart_date:strfilter for observations created after this date/timeend_date:strfilter for observations created before this date/timeobservation_start_date:strfilter for observations with timestamps after this date/timeobservation_end_date:strfilter for observations with timestamps before this date/timeReturns:formattedResponseobject with attributes:response_coderesponse_body(list of requested observations from origin event)get_observation_attachmentsget_observation_attachmentsDownloads attachments for provided observation document.Parameters:observation:dictpreviously retrieved observation documentReturns:attachments_mappingdict:{
    'observationId': observation_id,
    'eventId': event_id,
    'attachments': [attachment_paths]
}create_observation_attachmentscreate_observation_attachmentsUploads attachments using provided dict to determine event id, observation id, and attachment locations.Parameters:attachments_mapping:dict:{
    'observationId': observation_id,
    'eventId': event_id,
    'attachments': [attachment_paths]
}Returns:A list offormattedResponseobjects for upload requests with attributes:response_coderesponse_body(list of requested observations from origin event)Formscreate_formcreate_formCreate new form in event.Parameters:form:dictdictionary corresponding to a valid form objectevent_id:intnumerical id for destination eventReturns:formattedResponseobject with attributes:response_coderesponse_body(created form document)update_formupdate_formReplace specified form with provided dictionary.Parameters:form:dictdictionary corresponding to a valid form objectevent_id:intnumerical id for destination eventform_id:intnumerical id for destination formReturns:formattedResponseobject with attributes:response_coderesponse_body(updated form document)clone_formsclone_formsCreate new form in event.Parameters:forms_list:listlist of dictionaries corresponding to valid form objectsevent_id:intnumerical id for destination eventReturns:A dictionary mapping provided form names and ids to created forms and ids.Teamssession.add_user_to_teamadd_user_to_teamAdd specified user to specified team.Parameters:user:dictuser objectteam_id:intnumerical id for destination teamReturns:formattedResponseobject with attributes:response_coderesponse_body(updated team document)Rolesget_rolesget_rolesFetch roles for own MAGE user.Parameters:None.Returns:formattedResponseobject with attributes:response_coderesponse_body(list of available roles for user)grant_event_rolegrant_event_roleGrant event-specific role to specified user.Parameters:event_id:intnumerical id for destination eventuser_id:strid for user to grant rolerole:strrole to grant (owner, manager, guest)Returns:formattedResponseobject with attributes:response_coderesponse_body(created role document)