Custom API

 

File to modify 

1. Open the parameters file “UserDir/Powertivity/Default.xml”
2. Include the XML such as following, inside the <File> … </File> tags

Example code

---

Tags

<Server></Server>

• Position: Inside <File>…</File>
• Parameter: Id ; Hidden name of the upload protocol. Must be different between various <Server>
• Multiple <Server> possible per <File>

<Label/>

• Position: Inside <Server>…</Server>
• Parameter: Value ; Visible name in the custom menu
• Only one <Label> per <Server>

<Debug/>

• Position: Inside <Server>…</Server>
• Parameter: Value ; Used for debugging purposes, among the following values:
  • on: Popup showing the URL call and the result ; all requests of Server are in “Debug” mode
  • off: no popup
• Only one <Debug> per <Server>

<Request></Request>

• Position: Inside <Server>…</Server>
• Parameter: Value ; Id used for Goto instructions. The first <Request> will be used when user triggers the upload. Value can only have alphanumerical characters ([a-zA-Z0-9])
• Multiple <Request> possible per <Server>

<ReqUrl/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; URL that will be called
  • In case of “choice” ReqType, should be in the form of Value=”<value>6.1.n.1</value><title>6.1.n.2</title>”
  • In that case, Response will be in the form of <ReqResponse Value=”<value>([^<]*)</value>”/>
• Only one <ReqUrl> per <Request>

<ReqType/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; Type of URL call, among the following values:
  • get: hidden GET call
  • post (resp. put, options, patch): hidden POST call (resp. put, options, catch…)
  • upload: hidden POST call, include the presentation or selection in a multi-part content
  • form: GET call visible to the user (in a PowerPoint popup)
  • follow: GET call visible to the user (in a classical Web Browser)
  • fixed: no URL call, the URL is used as content, and processed
  • choice: no URL call, the URL is describing the various options to choose from, result is the user choice
  • input: no URL call, the “ReqUrl/Value” parameter is proposed to the user, and the edited value returned
  • inputs: no URL call. Multiple parameters are proposed to the user (see <ReqInput/>) and the edited values are stored in variables (e.g. $aa.0.1.0$). Global result is an aggregation of the input results, excluding the passwords
  • msg: no URL call, the Value parameter is shown to the user
• Only one <ReqType> expected per <Request>

<ReqDebug/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; Used for debugging purposes, among the following values:
  • on: Popup showing the URLcall and the result
  • off: no popup
• Only one <ReqDebug> expected per <Request>

<ReqHeaders/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; Specific headers that should be included in request, separated by the | character
• Only one <ReqHeaders> expected per <Request>

<ReqBody/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; Specific body that should be included in the POST request ;
  • in case of JSON, the “Content-type: application/json” header should be included in the <ReqHeaders>
• Only one <ReqBody> expected per <Request>

<ReqParam/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; Specific to “upload” type: variables sent in multi-parts request ; separated by the | character
• Only one <ReqParam> expected per <Request>

<ReqFileName/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; Specific to “upload” type: name of the file variable expected
• Only one <ReqFileName> expected per <Request>

<ReqThumbName/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; Specific to “upload” type: if not null, name of the thumbnail variable expected ; if not provided, the thumbnail will not be created and uploaded
• Only one <ReqThumbName> expected per <Request>

<ReqFormat/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; Specific to “upload” type: can be among:
  • pdf
  • png
  • jpg
• Only one <ReqFormat> expected per <Request>

<ReqInput/>

• Position: Inside <Request>… </Request> of type « inputs » (exclusively)
• Parameter: Type ; among the following values: text, password or checkbox (values “on” and “off”)
• Parameter: Title ; title before the input field
• Parameter: Def ; default value in the field. Can be a variable value (e.g. $aaa.0.1.0$)
• Parameter: Var ; variable name where the result will be stored (if « aaa », will be stored in $aaa.0.1.0$)
• Multiple <ReqInput> possible (and likely) per <Request>

<ReqReplace/>

• Position: Inside <Request>… </Request> 
• Parameter: From; text to be looked for
• Parameter: To ; text to be replaced
• Triggers a replacement of the “From” by the “To” within the response string (after request, before regex extraction from the request) 

<ReqResponse/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; Regex pattern to be found in URL response
  If Regex pattern found in response, variable $1.1.1.0$ is defined
• Parameter: Var; Variable name to be used to store the found pattern.
  if Var=”NAME”, the variable $NAME.0.1.0$ is defined
• Example: <ReqResponse Value=”<popup>([a-z]+)</popup>”/> <ReqResponse Value=”<test>([a-z]+)=”([a-z]+)”</test>”/>
• Multiple <ReqResponse> possible per <Request>

<ReqIf/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; Regex pattern to be found in URL response
• Parameter: Goto ; Next Request ID, in case Regex pattern is found ; Can be “Stop”
  Note that the ” character should be replaced by 2 x ‘ characters
• Multiple <ReqIf> possible per <Request>

<ReqGoto/>

• Position: Inside <Request>…</Request>
• Parameter: Value ; Next Request ID, in case all the ReqIf didn’t trigger positively ; Can be “Stop“
• Only one <ReqGoto> expected per <Request>

<ReqLoopVar/>

• Position: Inside <Request>…</Request>
• To allow a loop of the given Request, based on a given variable (or multiple variables)
• Parameter: Value ; Variable to be used (e.g. “$1.1.n.1$”, or “$1.1.n.1$,$1.1.n.2$”). The loop will be done on the various possible values for n (e.g. $1.1.1.1$, $1.1.2.1$, etc.)
• Only one <ReqLoopVar> expected per <Request>

<ReqLoopAfterGoto/>

• Position: Inside <Request>…</Request>
• To give the next steps, after all iterations of a loop (ReqLoopVar)
• Parameter: Value ;  Next Request ID ; Can be “Stop“
• Only one <ReqLoopDeep> expected per <Request>

---

Variables

• Position: Inside any parameter string (usually Value=””)
• Format: $<Name of request>.<Number of ReqRequest>.<Number of occurrence found>.<Number of regex sub-pattern>$
• When indicated by a Var =”aaa” parameter, the target variable is $aaa.0.1.0$. 
• When the variable name starts with “save” (e.g. “savetext”), the variable will be saved locally, and available between request occurrences 
• Example: $1.1.1.0$
  • Special: “$1file.0.0.0$” for file name
  • Special: “$1file.1.0.0$” for file name without file extension

---

Icon

• Position: add “upload.gif”, a 25×25 GIF file in your “Documents\Powertivity\” folder
• It customizes the look of the menu button related to your custom upload functions

---

Notes

• Inside a parameter, double quotes are written as two single quotes (” -> ‘ + ‘)