User Manual How to use this document Each section starts with an audience statement. If you are not the target audience, please feel free to skip that section. Basics Audience: all users The travelers are electronic documents created from predefined templates. A traveler lists the tasks in order to finish the work defined by the released work template. The user records data and notes when performing the tasks. Travelers can be grouped into working packages named binders. Besides web based user interface, the traveler application provides a simple HTTP API for other applications to operate templates, travelers, and binders. What is a template? A template is the documentation for a predefined process. A user can execute the process multiple times and collect data during the executions. A template can contain multiple sequenced sections, and each section can contain instructions and inputs. A user can design a template in a WYSIWYG (what you see is what you get) editor. Each template has a life cycle, and can be managed by users with special roles. Users can only create travelers from the released templates. The draft templates section describes the details of how to work with templates. There are two types of templates — normal templates and discrepancy templates. A normal template defines a sequence of actions and data points to collect. A discrepancy template is for the QA process, in which the data collected in a normal process is examined and requested for correction. A normal template can be used on its own, while a discrepancy template has to be used together with a normal template. What is a traveler? A traveler is an electrical document that supports the execution of a predefined process in a normal template and to collect user input data and notes in the process. It also supports collections of discrepancy QA logs with a discrepancy template. A traveler has properties like title, description, deadline, locations, devices, and tags. The user can add/remove multiple tags into the tag list. Tags can be used to group and find travelers. A device is a special type of tag that represents a physical entity related to the traveler. The user creates a new traveler when initializing it from a released template. Its state can be changed to active, submitted for completion, completed, and frozen. A traveler, either finished or not, can be archived when it needs no more attention from users. Only the traveler owner can access the traveler when it is archived. A traveler owner can share her/his traveler with other users/groups. A user can also transfer the ownership of a traveler to another user. The users with written permission to a traveler can input values into an active traveler. The input history is kept with the traveler. Each input can also have user notes attached to it. Optionally, a traveler can contain the history of discrepancies. A traveler can be considered as the composition of a released form/template, the input data, the notes, and discrepancy logs: traveler = template + data + notes [+ discrepancy logs] The travelers section provides more detailed information about how to create, update, and manage travelers. What is a binder? A binder is a collection of works that a user puts together for easy management. The traveler is a typical type of work. It is like a virtual folder containing the works related to a specific topic. For example, an engineer can put all the travelers related to a specific device into one binder. A workshop manager can put all the travelers involved in the workshop into one binder. One traveler can be put into multiple binders. A work has properties like Sequence, Priority, Value, and color. The sequence is a counting number defining the order to perform the works. The priority is a counting number defining the importance, and one is the highest priority level. The value represents the planned cost or the earning that the work will contribute to a project as that used in earned value management. The color defines a status flag with a color code. A binder can be put into another binder. This is useful for higher management to oversee the progress of sub teams. For more details, see the binders section. Log in and out Besides this document page and the main page, all other resources are only accessible to authenticated users. Users can use their organization username and password to log in. Users are encouraged to log out when they do not work with the application. If not log out, a user’s session will expire after a period. When a user tries to access a resource URL on a browser with an expired session, the user will be directed to the login page, and be redirected back to the requested URL if login succeeds. When a page contains unsaved content and the session has expired, an error message will appear on the top of the page when the user tries to save. Log in the application in a new tab or page, and then save the change again. Do not close or navigate away from the page that contains the unsaved changes, otherwise the unsaved changes will be lost Ownership, roles, and access control The traveler application supports role based and attribute based access control. When a user requests to access a resource, both the user’s roles in the current session and the resource’s access related attributes are considered. The access is granted if either the role or the attribute allows. There are three special roles, admin, manager, and reviewer. A user can be associated with multiple roles. Only an admin can modify a user’s roles. Only a reviewer can review a submitted template to release. An admin or a manager is capable of reading and writing all resources in the application. The traveler application has three important entity types: template, traveler, and binder. Each type has three attributes to control the access, the ownership, sharing, and public accessibility. There are three levels of access privileges: no access, read, and write. The details are listed in the following table. access privilege details no access rejected when requesting to access an entity read view the representation of an entity, but will not be able to modify the entity write be able to view and modify the entity Every entity has an owner. The owner is the user who creates the entity. An entity’s ownership can be transferred to a different user by its current owner. The owner, by default, has the privilege to configure attributes of the entity including the sharing and public accessibility. The owner user can share an entity with other individual users or groups with read or write permission. The shared entity will also appear in the shared entity tab or the group shared entity tab of a user. The entity owner can configure an entity to be publicly readable or writable. All the public available entities are listed on the all public forms or all public travelers pages. Tabs and tables The templates, travelers, and binders pages use tabs to separate entities in different statuses. In each tab, the entities are listed in a table. There are two places that a button can be placed on a tabbed page. On each list page, when a button is located on top of the tabs, the button’s action is applicable to all the tabs and tables inside the tabs. When a button is located inside a tab, then the button’s action is only applicable to that tab and table. Around a table, there are 6 areas each of which either hold optional tools or display information. area location content 1 top left a select input to change the number of records shown per table page 2 top middle show a message when the data inside the table is in processing 3 top right a text input to filter all the columns in the table 4 bottom row text inputs to filter the corresponding table column 5 bottom left the numbers of entries out of the total number shown in the view 6 bottom right pagination controls Some tables have extra tools that allow a user to copy, export, or print the table. The traveler application uses the datatables js library for the tables in web UI. Many pages in the application are still on an old version of the library, and the tools are not supported by browsers due to the dependency on the flash technology. We are in the process of updating those pages to use the latest version of the datatables library. Print In most cases, the user can print the page to either PDF or a real printer with the browser’s print function. The traveler pages have a dedicated view to be print format friendly. On a traveler page, clicking on the Create PDF button will open a new tab of the print view. On the print view, the user can use the top toggles to show or hide the validation, notes, and details information. The traveler report page loads the table view of the data inside a group of travelers. The user can generate a PDF file or print the table with the tools on the page directly. Colors and graphical design The traveler application uses a color convention in the interface design. The buttons are colored according to the possible impact of the actions. primary information success warning danger Each traveler or binder has an estimated progress. The progress is visualized by a bar. The bar color and corresponding entity status is listed in the following table. progress bar status 0 / 7 initialized 2 / 7 active 6 / 7 submitted for completion approval or frozen approved completion Some progress bars have values on it. The formats of the value notations are listed in the following table. entity type progress bar values traveler 2 / 7 updated input number / total input number binder or entity in a binder 0 + 3 / 10 finished value + in-progress value / total value In a binder, a colored flag denotes the status of a work. flag status going well not going well completed failure not active Draft template Audience: traveler users, especially process template owner Before creating travelers, a user needs to design a template and release it after a review process. A traveler template mimics the paper traveler so that a process owner defines the sequence of actions and specifies the data to be collected in each step. Normal templates Most traveler use cases can be covered with normal templates. The user can define most common HTML input types, including numbers, date, short text, long text, radio button, checkbox, and file upload in a normal template. The user can also include instructive directions of text, diagrams, and formulas in a normal template. A normal template supports numbered sections for easy navigation and reference. Discrepancy template A discrepancy template can be used for a quality assurance (QA) like process. It is owned by the QA process owner, who has the responsibility to verify the result of a traveler. When a traveler is ready for quality assurance, a QA personal will check if the result meets the expectation. A discrepancy is logged if the work does not pass QA, which will be followed by a correction. The correction will be recorded in the traveler with data updates. Then a new QA iteration can be triggered. A released discrepancy template cannot used solely without being attached to a released normal template when creating a traveler. States and life cycle of a template The following diagram shows the state transition of a template and a released template. States and life cycle of templates There are two groups of templates: draft and released. Only a released template can be used to create a traveler. The traveler application supports the review and approval process of templates. A template is a draft and editable when created. When a draft template is not needed any more, the owner can archive it. The owner can clone an archived template to generate a new draft template if some work needs to be picked up later. When a draft template is ready for review, its owner can request one or more reviewers to check if the template is good to release. A reviewer can either approve or request for change. When any reviewer requests a change, the review process ends and the form becomes editable. All the reviewers must approve before a template can be released. When a user releases a template after a successful review process, a new released template is created. The user can choose to archive previously released templates from the same draft template of different versions. If the draft template is a normal template, the user can choose to attach a released discrepancy template with it. A released template can be archived. Travelers can be created from an archived released template. This happens when the process is obsoleted or a new process is available. Tabs on the template page The templates are listed in different tabs according to their status and ownership like the following. Please click the tab to see what are the content to be included in each tab. My draft templatesTransferred draft templatesShared draft templatesGroup shared draft templatesUnder review templatesApproved and released templateArchived draft templates All draft templates created by the current login user All draft templates transferredd to the current login user from other users All draft templates shared with the current login user All draft templates shared with the current login user's group All templates owned by the current login user and submitted for review All templates whose review process was closed All templates owned by the current login user and archived Template builder The template builder is a what-you-see-is-what-you-get editor. It is the starting point to use the traveler application for most users. Template type Log in the traveler application, and navigate to the Forms or Templates page. Then click the New form button. A new page will load the following page. New template The user needs to set the new template’s name, and choose the type. The default type is normal. The discrepancy type is for QA process in order to check the discrepancy of a work. Click Confirm to go to next step. Always start with the normal type for your first try. Template components A new template has no inputs inside. The user can add new components, update the attributes of an existing component, duplicate a component, and adjust the location of a component. Basic input components The template builder support 8 basic inputs types: input name usage properties Checkbox specify a boolean value, true or false Label, User defined key, Text, Required Checkbox set select any number out of multiple options Set label, User defined key and Text for each option Radio choose one out of multiple options Label, User defined key, Text, Required, Radio button value Text a single line text to record Label, User defined key, Placeholder, Required, Help Figure not a user input, a visual instruction for traveler user Select an image, Image alternate text, Width, Figure caption Paragraph multiple line text to record Label, User defined key, Placeholder, Row Required, Help Number either an integer or a float value Label, User defined key, Placeholder, Help, Min, Max, Required Upload file use upload file Label, User defined key, Help, Required Other types Text/Number/Date/Date Time/Email/Phone number/Time/URL HTML5 input types with validation support Label, User defined key, Placeholder, Help, Required Each input is specified by a list of properties. Some properties control the input presentation, and some control its behavior, and some are for internal traveler application. The details of the input properties are listed in the following table. property name usage notes Label appears in front of the input, short description default as “label”, SHOULD be short and unique in the template User defined key does not render in the template, but used for report and API MUST be unique within the template; only letter, number, and “_” allowed (Example: MagMeas_1) Radio button value appears behind the radio button the value will be recorded in DB; each radio button value MUST be unique within the radio group Required whether the input is required when an input is required, the value MUST be present to pass template validation; for checkbox, required means it MUST be checked Placeholder appears inside the input before the user touches a short hint to the user Select an image upload an image for the figure choose an image file from local file system and then click upload Image alternate text the text appears in the place when the image is not loaded meaningful text for the image Width the width of image appearing in the template when the image is too large, use this property to resize it. The unit is pixel, and the height will be adjusted accordingly to keep the original aspect. Figure caption appears below the image a long text to describe the image Row the number of rows for the text box provide enough space so that the user can input or view the text without scrolling Min minimum allowed value for a number useful for validation Max minimum allowed value for a number useful for validation Help appear below the input a long hint to the user for the input A note on multiple choice input in HTML The select element with multiple attribute of true was designed to implement a multiple choice in HTML as in rfc1866. However, a user can face various challenges when interacting with it. On a desktop device, a user needs to hold a special key while using mouse to click on options. On a mobile device, a user needs to click on the element in order to reveal the options. Many find that a set of checkbox input has a better user experience, like this example on MDN. We use checkboxes to implement multiple choice in the traveler form builder. Advanced components Currently, the builder supports two advanced controls, section and rich instruction. The section is for easy navigation and reference of a traveler. When a template has sections, a floating navigation will be generated on the right side of the traveler page. With the navigation, the user can jump to a section with a click. This is helpful when a template is several pages long. With rich instruction, a user can add math formulas, web links, images, and lists to the template. This is useful when the user needs a rich format editor to compose the paragraph. Note that the image added into the rich instruction needs to be hosted on a location that a traveler viewer can access. It is different from the figure in basic input, which accepts an uploaded image file from the user and saved on the traveler server storage. Update, delete, or duplicate a component When hovering on an existing template component, the component will be focused and a set of buttons shows on the top right corner of the component as follows. The first button is to show or hide the attribute panel for the component. The second is to create a new component same to the current component. The third is to remove the current component from the template. Save changes Whenever you update the template by adding a new input, or updating an input’s attributes, or adjusting the locations of the inputs, you can save the change to the server by clicking the Save button. When the user tries to save a template, the builder checks if a component’s editor is still open. If it is, then the user will see an alert to finish the edit first. The user can either commit the change by clicking the Done button, or cancel the change by clicking the button again. Sequence number Sequence numbers are added automatically to the components. There are three levels of numbers: the section is the top level, the second is the rich instruction, and the third is the basic input. 1 Section name 1.1 instruction for what to do 1.1.1 some data to collect When a new component is added, or a component’s location is adjusted, the numbers are updated automatically. For the templates created with an older version of the builder, there might not be numbers. The user can generate the numbers by clicking the Generate numbering button. Adjust component location Click the Adjust location to enter the location adjustment mode. The user can drag and drop a component to a different place. The sequence number will be updated every time a component’s location is changed. Click the Done to exit the location adjustment mode. Note that the changes will not be saved until clicking the Save button. Import other templates In order to make the composition of a new template fast, the user can import the components inside any draft template or released template into the current builder. After importing, the user can adjust the location or remove components. Preview and validation The user can preview the saved template any time when clicking the Preview button. The preview page renders the template and the validation logic specified in the builder. The user can see the validation result when clicking the Show validation button. Save as a new template The user can save the template in the builder as a new template. The new template can be found in the my draft templates list. Clone a template Ownership transfer Template version control When a watched property of a template is updated on the server (the user clicks the save button), the template version will be incremented. The watched properties include the title, description, and HTML. The template viewer or builder always renders the latest version when refreshed. The user can view the versions with HTML changes by clicking the Version control button. The user can choose any two versions to compare them side by side. Note that not all the details of template HTML are viewable when rendered, e.g. the input validation rules like min and max value of a number. The user can “revert” the template to an old version by clicking the Use button. In order to record the change, a new version is created for the template. Template review and release process A traveler can only be created from a released template. A released template is created when a draft template is approved by the reviewers and released after that. When the owner finishes editing a template, s/he can request a template review by click on the Submit for review button. All the submitted templates are listed on the under review templates tab. On the template review page, the template owner can add or remove reviewers. A reviewer is a user with the reviewer role. When any reviewer requests change in the form, the review process is stopped. All past review results and comments for specific versions are viewable for future reference. The review process restarts when the owner makes changes and submits for review again. When all the reviewers approve the template of the current version, the Release button will appear on the template page. When the owner releases the approved template, a new released template is created. The approved template is listed on the approved and released template table. Reviewer Audience: admin and reviewer A normal traveler user cannot review templates. The admin needs to add the reviewer role to the users who want to perform the task. A reviewer sees Reviews link on top of the traveler page. The reviews page lists all the active templates under review. The reviewer can approve or request for more works for a template. A template needs to be approved by all the reviewers before release. A single rework request from any reviewer will terminate the review process, and the template becomes editable again. A reviewer can request change for a template that s/he has approved before it is released by the template’s owner. Released template Audience: traveler users When a templated is released after the review process, a new released template will be created and listed in the released template page at /releasedforms/. A released form can be in a normal active status or an archived status. A user cannot create new travelers from an archived released template. The admin can prevent the usage of a released template by Obsolete it. The released templates are versioned. When releasing a template, the traveler application will suggest the user to archive all the previously released templates that are still active and related to the template to the released. In this way, we can ensure there is only one released template for a specific process that has the latest updates. Traveler Audience: traveler users A user can create new travelers from released templates. The traveler owner can configure, share, active and approve the completion of a traveler. The traveler owner work with other users to input data and notes into a traveler in order to finish the task described by the traveler. A traveler can be located by its URL. The URL is like /travelers/longstringid/ where the longstringid is the traveler’s unique identity. The user can bookmark the traveler’s URL or send it to other users. A user needs to have at least read permission to view a traveler. Create a new traveler Audience: all who want to create a traveler The user can create new traveler(s) from any released template. Select one or more templates that you want to create new travelers, and click the Travel button. New traveler(s) will be created and listed in the My travelers table with initialized status. Traveler status Audience: traveler owners and others with write permission The allowed access of a traveler changes with its status. The transitions between statuses, and the allowed access at each status are shown in the following diagram, where r for read and w for write. The following table lists the status and corresponding allowed access for traveler data and traveler notes. status artifact allowed access new data no data available new notes read and write active data read and write active notes read and write frozen, submitted for completion, or complete data read only frozen, submitted for completion, or complete notes read and write archived data read only archived notes read only Update a traveler’s status Audience: traveler owner and other users with write permission A traveler’s possible statuses and allowed transitions among statuses are described in the traveler status section. The user can change an initial traveler’s status to active by clicking on the Start to work button when the traveler is ready to accept data. The user can change an active traveler to submitted for completion by clicking on the Submit for completion button on the traveler page. The user can change a submitted traveler to complete by clicking on the Approve completion button when the work is complete. If the work is not complete, click on the More work button to reject the submission. The user can change an active traveler to frozen by clicking on the Freeze button in order to stop accepting data in the traveler. Click the Resume button to resume work. Tabs in traveler page Audience: traveler owners and others with write permission The travelers are listed in different tabs according to their status and ownership. Please click the tab to see what are the content to be included in each tab. My travelersTransferred travelersShared travelersGroup shared travelersArchived travelers All travelers created by the current login user All travelers transferredd to the current login user from other users All travelers shared with the current login user All travelers shared with the current login user's group All travelers owned by the current login user and archived View a traveler Audience: traveler users The user can directly load the traveler in the browser with a traveler’s URL. If the user has only read permission of the traveler, the browser will redirect to a read-only view. On the travelers table, click on the icon in order to load the traveler page. In a traveler page, the top line is the traveler’s title. Below the title is the traveler status, and progress. The progress tells the number of inputs updated out of the total inputs. The numbers represent only rough progress estimation of the traveler. A traveler can be complete when some inputs have not be updated. The Details button shows/hides some detailed information of the traveler including the description, creation user/time and last update user/time. The details information is hidden by default. The Show validationHide validation buttons show/hide the validation information for the traveler inputs. The validation information include a summary section shown under the buttons, and a validation message under each input. The validation rules are defined in the form that is used as the active form. The Show notesHide notes buttons show/hide the notes under each input. The n icon shows the number of notes. The value displayed in an input is the latest value saved on the server. The history of changes is shown under each input including the submitted value, submitter id and submission time. When a traveler has several sections, a side navigation menu is created on the right side. When scrolling up and down the page, the section corresponding to the content in the current view is highlighted in the navigation menu. Update the data Audience: traveler users with write permission In order to update the data and notes of a traveler, the user must have the write permission of the traveler. A traveler’s data can be updated only when it is in the active status. When the traveler is in other statuses, all the inputs are disabled on the traveler page. Note on the traveler view page, the user cannot update data or notes on that page even if s/he has write permission. When the user inputs a new value in an input, two buttons will appear on the right side. Click the Save button to submit the change to the traveler server. Or click the Reset button to reset to the original value. All other inputs are disable when an input is touched. If the change is saved on the server, there will be a xSuccess message on the top of the page. If something is wrong, then an xError message will appear. Update the note Audience: traveler users with write permission In order to add a new note, click the icon under an input. Click the n icon to show/hide the notes, where n is the total number of notes, and 0 at the beginning. When the notes are shown, hove over a note, and will appear. Click the button to load the update modal. The modal has a text area with the current note content. Update the content, and click the Update button to save the change. Click the Delete button to delete the note. Click the Cancel button to dismiss the modal without any change. Only the note’s author or admin/manager can update or delete a note. Configure a traveler Audience: traveler owner The traveler owner has the permission to configure a traveler. The configuration options include traveler title traveler description deadline tags forms status Click the icon on the traveler list table in order to navigate to the traveler configuration page. On the configuration page, click on the Edit button to update the traveler title or description. The deadline is a date picker. Click the Add tags button to add a tag. If the traveler has a list of tags, click the button behind a tag to remove it. Manage templates in a traveler (deprecated) This feature was removed after we implemented a template release process. The rational is that we should not change the traveler specification (templates) once it is executed in the field. If there is any change to the template, there should be a new traveler based on a new released template. FAQ Audience: all users Q: I cannot save the updates and I have the write permission. A: If you see warning messages on the top of the traveler page when you made updates, then the warning message should include the reason. If your session is timed out, you can log in in a new browser tab or windows, and come back the current tab and continue. Q: My browser cannot find the traveler server. A: Please connect to VPN and load the traveler application URL. Q: How to delete a template, a traveler or a binder? A: You cannot delete an entity (a form, a traveler, or a binder) in the traveler application once it is created. You can archive them. You can always de-archive an entity from your “archived” tab, to work on them again. Q: How to correct the data or note in a traveler? A: You cannot “revise” the input data in a traveler. You can always input a new value into the input where you want to correct. You might also want to add a note to the input in order to explain the reason for the update. Q: I cannot update the data in a traveler. A: If you cannot load the traveler page, then you do not have permission to view the traveler, or the traveler does not exist, or the owner of the traveler has archived it. If you can load the traveler page, but the inputs are disabled, then you do not have the write permission, or the traveler is not active. Q: How to let other users contribute to a traveler? A: You need to share your traveler with them. Please see the ownership and access control section for more details.