Process template ImportExport

From RPM Wiki


Table of contents
1 Template import, export

1.1 Summary

1.1.1 Tag structure
1.1.2 Example .proc file

1.2 History

[edit]

Template import, export

[edit]

Summary

Allows a process to be saved to an XML file. All fields, fields groups, status levels & instructions, status triggers, global actions, and default columns are defined. When a user is starting a process they can shoes to upload a process xml file instead of a blank process.


Need This will allow us to set customers up very quickly with some basic process templates. We can also have a library of processes on our website for users to download and use. Use cases 1. Export 1.1. Select an existing process. 1.2. Click the “Download” link in the tool bar. The user is redirected to the “Process export” page. 1.3. Enter a description, edit the author & date if needed. Click Download. 1.4. The wizard redirects to the process details page and the IE “Save/open” dialog pops-up. Select “Save” to save the XML file. The “finished” page contains a link back to the process details. 2. Export again 2.1. Click the “download” link again. 2.2. The export wizard opens again and the description and author from last time are shown. The date will have been regenerated off the process “modified” time. 3. Import 3.1. From the “Process settings” page click “Add a process” 3.2. Select the “Import” option Won’t do The following are not imported or exported:

  • Forms
  • Default participant
  • File attachments
  • Template notes (since they aren’t intended to be shared)
  • Views (likely in a future version)
  • Commission variable map (likely in a future version)
  • Next form number (but prefix & minimum digits are exported)
  • Featured in start/select lists
  • Process permissions (“who may select/start”)

Details The file

  • XML file
  • Filename: “{PROCESS}.proc”
    • Example: “Quote.proc”
    • We don’t need a field on the export page for the user to make up their own name since the IE save dialogue already allows them to do that.
  • Includes some extra data we’ve introduced just for the export:
    • Description. A txt description of the process and what it is used for. The user enters this in the export wizard and it is saved with the process. IN future exports it is shown again and the us4er can modify it at that time.
    • Author. Who created this process. As with the description this is modified at export time. By default it will be the username of the form creator and their subscriber: “{USERNAME}, {SUBSCRIBER}”
      • Example: “John Doe, Bandwidth Place”
    • Date. The date of the process. This is not saved with the process, it is generated from the process “modified” each time an export is done. The user can edit it in the export wizard to be anything (even an invalid date). The format to present it to the user is MMM D, YYYY. Example: “Mar 5, 2004”
    • Version. This is the version number of the RPM deployment used to create the file. This will be important when we need to add features to process management but maintain backward file compatibility. This is generated automatically and not seen by the user.
      • Example: “3.0”

Import defaults Default values for new processes built off a .proc import. In general if data is missing just do what would be done now when starting a blank form without an import.

  • Process permissions: “No one” may start, “Staff users only” may select.
  • Not featured to “start” or “select”
  • Next form number: 1
  • Title variable: May be in the XML file, but if not: set to null.
  • Form number prefix & minimum digits can be specified. If they aren’t use no prefix and 4 minimum digits.
  • Field permissions may be specified in the XML file, but if they aren’t use the defaults from the field specifications (See the “New edit fields interface” feature in this spec).
  • Reference fields may be featured (‘Start link on details page”). If the “featured” tag is not in the definition of a field, just treat it as not featured.
  • Global action owner: The owner of the global action is exported including the specific assignment category or staff name if applicable. If an exact match can’t be found in the subscriber doing the import, just set the new global action to an owner of “form owner”.
  • Status levels. Every process must have at least one status level, so if there are no valid status levels defined in the file do the same thing as a manually added black process: create a single status level called “New”
  • If default columns are missing for a user type (staff or agent) then use the built-in process management default columns (like when starting a blank template without an import)
  • Import sets the “Added” & “Modified” times and the “by” of each one to the user who performed the import.
  • If the select method for a list or supplier reference isn’t specified (“single”, “multi”, “fixed”) then assume “single”.

Validation The import wizard will check the XML file to make sure everything is valid (field types, parents, etc.) and report to the user anything that is invalid. They can continue if they want, but these invalid things will be ignored (not created). They can not continue at all if the file/process itself isn’t valid:

  • Process/file
    • Invalid: Missing name. No “rpmsoftware.com” namespace declaration. No “Process” tag.
    • Continue anyway: No description, date, or author. No titleVar. No number specifications.
  • Fields
    • Invalid: A field is invalid if it has no name, a reserved name, a duplicate name, no type, an invalid type. Also if it requires a parent but no parent is specified or a parent is specified that is invalid. A Shared field who's "parent" is not found or not specified. A Shared field is also invalid if the other shared field options are not valid.
    • Continue anyway: If the field does not require a parent ignore any parent specification. If the permissions aren’t specified or are incorrectly specified, just use the defaults (See “Import defaults” above). Belongs to an invalid or missing field group (will belong to no group).
  • Field groups
    • Invalid: A missing, duplicate, or reserved name. A missing or invalid field. A missing or invalid value (this will require checking agents, customers, etc. of the subscriber doing the import). A missing or invalid effect.
  • Status levels
    • Invalid: A missing or duplicate name
  • Status triggers
    • Invalid: A missing or invalid variable. A missing or invalid status level.
  • Default columns
    • Invalid: A column is invalid if it refers to a missing or invalid field. Note that some columns may not be fields like “Status” and “Modified by”. Those columns must be an exact text match to what they are referring to or you move on and assume they are a field name.
    • Limit. CR 6476 introduced a limit on the number of columns. Only import valid columns up to this limit then ignore any others. In other words, invalid columns do not count towards the limit.

Export

  • Do not include things that are in the recycle bin
  • Export does not update the “Modified” time of the process.
[edit]

Tag structure

  • <?xml version="1.0" encoding="utf-8"?> (required)
  • <rpm:Process xmlns:rpm=”urn:rpmsoftware.com:Process”> Defines our namespace (tag is required, namespace attribute is not)
  • <version> The version of RPM used to create this XML (if missing assume “3.0”)
  • <name> This is the name of the process (required)
  • <date> The date specified during export
  • <description> The description specified during export
  • <author> The author specified during export
  • <titleVar> A field displayed in the form’s page title
  • <number> Form numbering details
    • <prefix> The prefix added to every number
    • <minimum> The minimum number of digits not including prefix
  • <displayplural> Does RPM pluralize the template name when it is in use?
  • <agentautoaddagentparticipants> Automatically add agent participants on form edit?
  • <permissions>
    • <addParticipantChangeOwner> Describes the Process Role Permission required to add participants to a form or change the form owner. "Start", "Edit"
    • <addDeleteRepeatingFields> Describes the Process Role Permission required to add or delete repeating field sets for a form. "Start", "Edit"
    • <editTrashNotes> Describes the Process Role Permission required to edit or trash notes in a form. "Start", "Edit"
  • <repeating> Describes the "repeating field" capabilities of the template.
    • <enabled> Are repeating fields enabled? “true” or “false”
    • <addlink> The text that appears in forms when adding a new set of repeating fields
  • <fields> The data fields
    • <field>
      • <name> (required)
      • <type> (required)
      • <repeating> “true” or “false”
      • <value> (For “Fixed link” fields only)
      • <group>
      • <parent>
      • <sharedparent> (For Shared Fields only) The name of the field
      • <sharedtype> (For Shared Fields only)
      • <customfieldname> (For Shared Fields whose <sharedtype> value is "CustomField" only)
      • <formula> (For Formula Fields only)
        • <operator> "Add", "Subtract", "Multiply", "Divide"
        • <primaryInputField> The name of the field
        • <secondaryInputField> The name of the field
      • <select> “single”, “multi”, or “fixed”
      • <featured> “true” or “false”
      • <supplier> Used for “Supplier (fixed)” fields only, ignore otherwise
      • <options> Used for lists, ignore otherwise
  • <option> Use as many as needed
      • <permissions>
  • <agent>
  • <staff>
  • <customer>
  • <fieldGroups> The field groups
    • <fieldGroup>
      • <name> (required)
      • <fieldName> A field name or “Status” (required)
      • <value> Most variable types will have a single value inside this tag. Date & money variables have two values and there are contained in a <from> tag and a <to> tag inside the <value> tag. (required)
      • <effect> (required)
  • <statusLevels> The status levels
    • <statusLevel>
      • <name> (required)
      • <autoarchive> “true” or “false”
      • <userselectable> “true” or “false”
  • <statusTriggers> The status triggers
    • <statusTrigger>
      • <fieldName> (required)
      • <toStatusLevel> (required)
      • <canSetOldStatus> “true” or “false”
  • <globalActions> The global actions
    • <globalAction>
      • <onStatusLevel> (required)
      • <action> (required)
      • <owner> if it is “staff” or “assignment category” then it should have a “name” attribute (see example below) (required)
      • <days> (required)
      • <hidden> “true” or “false”
  • <defaultColumns> The default columns
    • <staff>
      • <column> Use as many as needed
    • <agent>
      • <column> Use as many as needed
    • <customer>
      • <column> Use as many as needed
[edit]

Example .proc file

<?xml version="1.0" encoding="utf-8"?>
<rpm:Process xmlns:rpm="urn:rpmsoftware.com:Process">
	<version>3.0</version>
	<name>My Process</name> 
	<date>Jan 1, 2003</date>
	<description>This is a test process</description>
	<author>Jade Ohlhauser, RPM Software</author>

	<titleVar>Partner</titleVar>

	<number>
		<prefix>MY</prefix>
		<minimum>4</minimum>
	</number>

       <repeating>
                <enabled>true</enabled>
                <addlink>Add repeating fields</addlink>
       </repeating>
       <displayplural>True</displayplural>
       <agentautoaddagentparticipants>True</agentautoaddagentparticipants>
       <permissions>
            <addParticipantChangeOwner>Edit</addParticipantChangeOwner> 
            <addDeleteRepeatingFields>Start</addDeleteRepeatingFields> 
            <editTrashNotes>Edit</editTrashNotes>
       </permissions>
       <fields>
               <field name="repeating field">
                       <type>AgentCompany</type>
                       <select>single</select>
                       <repeating>true</repeating>
                       <featured>true</featured>
               </field>
		<field>
			<name>Opportunity name</name>
			<type>Text</type>
			<group>Locked fields</group>
		</field>
		<field>
			<name>Partner</name>
			<type>AgentCompany</type>
			<permissions>
				<agent>ReadOnly</agent>
                               <customer>Hidden</customer>
			</permissions>
			<featured>true</featured>
		</field>
               <field name="Partner contact">
                       <type>sharedfield</type>
                       <sharedparent>Partner</sharedparent>
                       <sharedtype>PrimaryContact</sharedtype>
                       <permissions>
                              <agent>Hidden</agent>
                       </permissions>
               </field>
		<field>
			<name>Sales rep</name>
			<type>AgentRep</type>
			<parent>Partner</parent>
			<permissions>
				<agent>ReadOnly</agent>
			</permissions>
		</field>
		<field>
			<name>Service</name>
			<type>List</type>
		        <select>multi</select>
 			<permissions>
				<agent>ReadOnly</agent>
			</permissions>
		</field>
              <field name="primary money">
                       <type>Money</type>
                       <repeating>false</repeating>
              </field>
              <field name="secondary money">
                       <type>Money</type>
                       <repeating>false</repeating>
              </field>
             <field name="Sum money fields">
                       <type>Formula4</type>
                       <formula>
                             <operator>Add</operator>
                             <primaryInputField>primary money</primaryInputField>
                             <secondaryInputField>secondary money</secondaryInputField>
                       </formula>
                       <repeating>false</repeating>
             </field>
	</fields>

	<fieldGroups>
		<fieldGroup>
			<name>Locked fields</name>
			<fieldName>Status</fieldName>
			<value>New</value>
			<effect>Unlock</effect>
		</fieldGroup>
	</fieldGroups>
	
	<statusLevels>
		<statusLevel>
			<name>New</name>
                       <autoarchive>false</autoarchive> 
                       <userselectable>true</userselectable> 
		</statusLevel>
		<statusLevel>
			<name>In Progress</name>
		</statusLevel>
	</statusLevels>
	
	<statusTriggers>
		<statusTrigger>
			<fieldName>Partner</fieldName>
			<toStatusLevel>In Progress</toStatusLevel>
			<canSetOldStatus>false</canSetOldStatus>
		</statusTrigger>
	</statusTriggers>
	
	<globalActions>
		<globalAction>
			<onStatusLevel>New</onStatusLevel>
			<action>This is an action</action>
			<owner>FormOwner</owner>
			<days>5</days>
			<hidden>true</hidden>
		</globalAction>
	</globalActions>

	<defaultColumns>
		<staff>
			<column>Number</column>
			<column>Owner</column>
			<column>Status</column>
			<column>Partner</column>
			<column>Action required by me</column>
		</staff>
		<agent>
			<column>Number</column>
			<column>Owner</column>
			<column>Status</column>
			<column>Action required by me</column>
		</agent>
               <customer>
                       <column>Number</column>
                       <column>Owner</column>
                       <column>Action required by me</column>
                       <column>Started</column>
                       <column>Started by</column>
                       <column>Modified</column>
                       <column>Modified by</column>
                       <column>Files</column>
                </customer>
	</defaultColumns>
</rpm:Process>

Pages • Add a process (modify: add import option, staff only) • Process details (modify: add export link, staff only) • Process export (new, 1-page wizard, staff only) Security • Importing or exporting a process requires the “Subscriber settings” privilege.

[edit]

History

  • Mars: Feature added
Retrieved from "http://www.rpmsoftware.com/wiki/index.php/Process_template_ImportExport"
  • This page was last modified 20:27, 24 Nov 2009.
  • This page has been accessed 5273 times.