Difference between revisions of "App projects"

From Resco's Wiki
Jump to navigation Jump to search
 
(67 intermediate revisions by 3 users not shown)
Line 1: Line 1:
An app project is a customized version of mobile application dedicated for a particular set of users. Or more precisely, the application remains the same, but each project may have different set of data and functions available.
+
An app project is a customized version of the mobile application dedicated to a particular set of users. Or more precisely, the application remains the same, but each project may have a different set of data and functions available.
  
Administrators use Woodford to create various projects and publish them. App users synchronize their mobile app to access the necessary functions and data.
+
Administrators use [[Woodford]] to create various projects and publish them. App users synchronize their [[Resco mobile apps|mobile app]] to access the necessary functions and data.
  
 
== What's an app project ==
 
== What's an app project ==
Line 10: Line 10:
 
* [[Business logic]]
 
* [[Business logic]]
  
App projects are represented as a set of metadata. The customizations are saved on the CRM server.
+
App projects are represented as a set of metadata. The customizations are saved on the backend server.
 
* For installations with Microsoft Dynamics, app projects are saved directly in Microsoft Dynamics.
 
* For installations with Microsoft Dynamics, app projects are saved directly in Microsoft Dynamics.
* For installations with Salesforce and [[Resco CRM server]], app projects are saved in Resco CRM.
+
* For installations with Salesforce and [[Resco Cloud]], app projects are saved in Resco Cloud.
 +
 
 +
App projects are designed for a particular user role. For example, you can create one project for field technicians and a different one for the manager.
 +
 
 +
== Grouping app projects ==
 +
 
 +
Optionally, you can group app projects into apps. Each project belongs to a group. Users of [[Resco mobile apps]] can then switch between apps.
 +
 
 +
<gallery mode="packed" heights="150px">
 +
File:Apps and app projects.png|List of app projects in groups
 +
File:App project properties.png|Configure the '''App''' group in project properties
 +
File:Switch app from app.png|Go to [[Setup]]/Settings to change between apps
 +
File:Switch app from webapp.png|In the web app, switch using the profile button
 +
</gallery>
 +
 
 +
You can create app groups when creating a new app project or when editing the properties of an existing app project: Set the '''App''' to "Create a new app..." and enter a '''New App Name'''.
 +
 
 +
To delete an app group, simply remove all app projects from the group, either by assigning them to a different app group or by deleting them.
  
 
== Project properties ==
 
== Project properties ==
  
Select '''App projects''' from the '''Administration''' menu of [[Woodford]] to display a list of existing projects. The following project properties are displayed in the list:
+
Select '''App Projects''' from the '''Administration''' menu of [[Woodford]] to display a list of existing projects. The following project properties are displayed in the list:
 +
 
 +
; App group: App projects can be grouped into apps. If you don't use this feature, all projects are in a single group called "Default". You can set the app group when creating the app project and modify it using the '''Properties''' button > '''App''' field.
  
 
; Icon: The icon offers a visual clue about the state of projects.
 
; Icon: The icon offers a visual clue about the state of projects.
:* Blue arrow-up sign: The latest version of the project has been published.
+
:* [[File:Active project.png]] Green check mark: The latest version of the project has been published.
:* Grey exclamation mark: If a project has a grey icon with exclamation mark, it means the project is ''dirty'', i.e. there has been a change in the project but it was not published after making these changes.
+
:* [[File:Draft project.png]] Grey exclamation mark: If a project has a grey icon with an exclamation mark, it means the project is ''dirty'', i.e. there has been a change in the project but it was not published after making these changes.
:* Red no-entry sign: Project has been deactivated.
+
:* [[File:Inactive project.png]] Red no-entry sign: Project has been deactivated.
  
 
; Name: You can enter any name for your project. As you create more projects, an intuitive name will help you identify them.
 
; Name: You can enter any name for your project. As you create more projects, an intuitive name will help you identify them.
 +
 
; Priority: When you create more projects for the same security role, the one with a higher priority is used.
 
; Priority: When you create more projects for the same security role, the one with a higher priority is used.
 
:* For example, if you create two mobile projects for a role Salesperson, one with the priority number 10 and second with 100, the second one will be used when the application synchronizes (since it has a higher priority number).
 
:* For example, if you create two mobile projects for a role Salesperson, one with the priority number 10 and second with 100, the second one will be used when the application synchronizes (since it has a higher priority number).
Line 31: Line 51:
 
; Type: For internal CRM users (usually employees), use '''Standard User'''. See [[External users]] for information about the other options.
 
; Type: For internal CRM users (usually employees), use '''Standard User'''. See [[External users]] for information about the other options.
  
; Format
+
; Format {{Anchor|Format}}
 
: '''Format 1 (Packed)''' means that the project was created and used by Silverlight Woodford. The project is stored in CRM as a Note attachment associated to a Mobile Project record. When a Format 1 project is opened using HTML Woodford, the project is updated to Format 2. We recommend exporting Format 1 projects before opening them in Woodford HTML.
 
: '''Format 1 (Packed)''' means that the project was created and used by Silverlight Woodford. The project is stored in CRM as a Note attachment associated to a Mobile Project record. When a Format 1 project is opened using HTML Woodford, the project is updated to Format 2. We recommend exporting Format 1 projects before opening them in Woodford HTML.
 
: '''Format 2''' means that the project was opened or created using HTML Woodford. It is no longer stored as a Note attachment; each project file is stored as a record in Mobile Project Item entity. This allows multiple users to work concurrently on the same project (on different parts of the project), and prevents projects from accidental corruption, e.g. due to bulk deletion of notes or using cloud storage for note attachments. Format 2 projects can still be opened using Silverlight Woodford, however, HTML Woodford is necessary to publish them.
 
: '''Format 2''' means that the project was opened or created using HTML Woodford. It is no longer stored as a Note attachment; each project file is stored as a record in Mobile Project Item entity. This allows multiple users to work concurrently on the same project (on different parts of the project), and prevents projects from accidental corruption, e.g. due to bulk deletion of notes or using cloud storage for note attachments. Format 2 projects can still be opened using Silverlight Woodford, however, HTML Woodford is necessary to publish them.
 +
 +
{{Note|HTML version of Woodford can only delete Format 2 projects. Usually, the upgrade from Format 1 to Format 2 happens seamlessly, when you open a Format 1 project. If you are cleaning up old projects and you attempt to delete a Format 1  project, this will fail. Open the project and save it immediately; then you can delete it.}}
  
 
Additional properties are available when you create projects:
 
Additional properties are available when you create projects:
; Role: Select the security role(s) for which you want to create the mobile project. You can create different mobile versions (projects) for different users based on their CRM role.
 
  
; Template: Select one of the pre-defined app templates, such as sales or field service. Templates come with pre-configured home screen and defined lists and views designed for a particular use case.
+
; Roles: Select one or more security roles (or profiles in Salesforce) for which you want to create the project. You can create different app projects for different users based on their roles (profiles).
 +
 
 +
; Template: Select one of the pre-defined app templates, such as sales or field service. Templates come with a pre-configured home screen and defined lists and views designed for a particular use case.
 +
 
 +
; Custom Version Identifier (Optional): Enter an optional text that identifies this particular project version. This information is displayed in the app.
  
 
== Toolbar functions ==
 
== Toolbar functions ==
Line 45: Line 70:
 
; New: Create a new project.
 
; New: Create a new project.
 
; Edit: Select a project and modify it. Alternatively, you can simply double-click a project.
 
; Edit: Select a project and modify it. Alternatively, you can simply double-click a project.
; Properties: Modify project's properties: Name, Role, and Priority.
+
; Properties: Modify the project's properties: Name, Role, and Priority.
; Show user: Display the list of users who receive the customization, i.e., users with a security role that's assigned to this project.
+
; Show Users: Display the list of users who receive the customization, i.e., users with a security role that's assigned to this project.
 
; Delete: Delete the project.
 
; Delete: Delete the project.
 
; Activate: Activate a previously deactivated project.
 
; Activate: Activate a previously deactivated project.
Line 53: Line 78:
 
; Export: Save a copy of the project to your local computer. This can be useful for backup.
 
; Export: Save a copy of the project to your local computer. This can be useful for backup.
 
; Clone: Create a copy of the selected project. You must enter a new Name, Role, and Priority. Cloning is useful when you want to duplicate a project for different users or when you want to experiment with Woodford and you don't want to lose your current project.
 
; Clone: Create a copy of the selected project. You must enter a new Name, Role, and Priority. Cloning is useful when you want to duplicate a project for different users or when you want to experiment with Woodford and you don't want to lose your current project.
; Restore: Return to the last published version of the selected project. If you accidentally delete Resco Mobile project’s note (or its attachment), which leads to losing your projecta and there is no backup, you can use the Restore button. It will create the project’s note and attachment from the last published version of the project. Only changes made after publishing will be lost and you don’t have to rebuild the project from scratch.
+
; Restore: Return to the last published version of the selected project. If you accidentally delete Resco Mobile project’s note (or its attachment), which leads to losing your project and there is no backup, you can use the Restore button. It will create the project’s note and attachment from the last published version of the project. Only changes made after publishing will be lost and you don’t have to rebuild the project from scratch.
; Recover: If you for example accidentally destroy your CRM organization and recover it without Resco entities, it is possible to recover the project from data synced on the Windows device. In case such situation happens, please contact us on mobilecrm@resco.net for further steps, from which the last one is using the Recover button.
+
; Recover: If you for example accidentally destroy your CRM organization and recover it without Resco entities, it is possible to recover the project from data synced on the Windows device. In case such a situation happens, please contact us on mobilecrm@resco.net for further steps, from which the last one is using the Recover button.
; Derive: Create a child project.
+
; Derive: Creates a child project.
 
; Flatten: Makes a standalone project from a derived project ("flattens" the hierarchy)
 
; Flatten: Makes a standalone project from a derived project ("flattens" the hierarchy)
; Check user: Specify a user name to display a list of all app projects where a user is involved, including project priority, so that you can see which customization is used.
+
; Check User: Specify a user name to display a list of all app projects where a user is involved, including project priority, so that you can see which customization is used.
; Commit: Send project changes to [[GitHub integration|GitHub]]
+
; Commit: Sends project changes to [[GitHub integration|GitHub]]
; Checkout: Retrieve project changes from [[GitHub integration|GitHub]]
+
; Checkout: Retrieves project changes from [[GitHub integration|GitHub]]
; Configure: Configure [[GitHub integration|GitHub]] connection
+
; Configure: Configures [[GitHub integration|GitHub]] connection
 
+
; Update: (Salesforce) Downloads metadata from Salesforce.
  
 
Once you open an app project for editing, you can use the following buttons and options.
 
Once you open an app project for editing, you can use the following buttons and options.
  
; Publish, Publish All: Once you are done editing an app project and you would like to push your changes to the mobile users, you need to publish your project. Next time your app users synchronize their apps, the customization will be applied on their devices.
+
; Publish, Publish All: Once you are done editing an app project and you would like to push your changes to the mobile users, you need to publish your project. Next time your app users synchronize their apps, the customization will be applied on their devices. See [[Publishing app projects]] for more information.
 
; Validate: Verify if your changes to the app project have not broken anything. Validation is also performed automatically before each publishing.
 
; Validate: Verify if your changes to the app project have not broken anything. Validation is also performed automatically before each publishing.
 
; Publish Version: Use the latest version, unless you know that your users have an old version of the app.
 
; Publish Version: Use the latest version, unless you know that your users have an old version of the app.
; Commit: See [[GitHub integration]] for more information.
+
; Commit: Send project changes to GitHub. See [[GitHub integration]] for more information.
 
 
  
 
Additional controls may become available once you select a function from the '''Project''' menu.
 
Additional controls may become available once you select a function from the '''Project''' menu.
Line 76: Line 100:
  
 
You can establish a parent/child relation between your projects. Child projects inherit all changes from the parent project except for the parts changed directly in the child project.
 
You can establish a parent/child relation between your projects. Child projects inherit all changes from the parent project except for the parts changed directly in the child project.
 +
 +
Here are the basic principles of how this functions:
 +
* Creating a child project creates essentially an empty project with a reference to the parent project, because it uses the project files of the parent project.
 +
* When you modify a setting or component in the parent project, and the child project does not have its own definition of the component, parent change is used.
 +
* When you modify a setting or component in the child project, the link to the parent is permanently broken for that component. Any further changes for the component in the parent no longer apply to the child.
 +
* Behind the scenes, project components are saved as files. For example, [[Sync Filter]] is stored as a single file. If you modify the sync filter in the child project, further changes in the parent will no longer be inherited.
 +
* In Woodford, many project components include the '''State''' column, indicating whether a component is inherited from the parent or overridden by the child.<br>[[File:Inherited or overridden.png|600px]]
 +
* You can use the '''Publish All''' button to [[Publishing app projects|publish the selected parent project]] including its all derived projects in a single click.
  
 
See also:
 
See also:
* For more information about project hierarchy, please check this section of one of our [https://youtu.be/2dM7TSdNGqU?t=1m59s webinars]. {{Badge|Webinar}}
+
* For more information about the project hierarchy, please check this section of one of our [https://youtu.be/2dM7TSdNGqU?t=1m59s webinars]. {{Badge|Webinar}}
 
* For information about the child project’s parts, whether they are inherited or changed in the child project, please check this additional [https://youtu.be/iLZ43KxGEW0?t=37m10s webinar]. {{Badge|Webinar}}
 
* For information about the child project’s parts, whether they are inherited or changed in the child project, please check this additional [https://youtu.be/iLZ43KxGEW0?t=37m10s webinar]. {{Badge|Webinar}}
 +
* [https://blog.resco.net/2015/10/27/woodford-project-hierarchy/ Woodford project hierarchy] {{Badge|Blog}}
 +
 +
=== Merge child changes to parent ===
 +
 +
The '''Flatten''' function allows you to merge changes in the child project into its parent.
 +
 +
For example, imagine three projects in a hierarchy:
 +
 +
* Parent
 +
** Child
 +
*** Grandchild
 +
 +
Continuing with this example, if you click '''Flatten''' on the project in the lowest level (in this case, the grandchild), all changes from the entire child hierarchy are merged into the highest project (in this case, the parent) and will result in a standalone project, when you will be given two options: export the project or create it as new one, free of any previous parent project reference.
 +
 +
The merge is perfomed in a cascade, all changes made in the grandchild project are merged into the child project and then into the parent project. Depending on whether you’ve made changes in both child projects on the same item, the changes from the grandchild overwrite changes in the child.
 +
 +
Before flattening the projects, please remember to back up all projects you wish to merge. Remember that sync filters of all entities are joined into one file, therefore, if you changed the grandchild's sync filter, flattening will overwrite sync filters in the child and parent project.
  
 
== Project menu ==
 
== Project menu ==
  
The '''Project''' menu in the left pane of Woodford allows you to access various functions and settings related to app projects, as well as all entities available in the back end.
+
The '''Project''' menu in the left pane of Woodford allows you to access various functions and settings related to app projects, as well as all entities available in the backend.
  
The menu includes a search bar. As you type letters, items in the menu are filtered. The search is not case-sensitive.
+
[[File:Project menu filtering.png|200px]] The top row of the menu serves you to simplify navigation:
  
 +
* Search: Use to quickly filter menu items. The search is not case-sensitive.
 +
* Disabled entities: Toggle to show or hide disabled entities.
 +
* Favorites: Click to show only menu items that you marked as favorite.
 +
* Expand/collapse all: Expand or collapse all submenus.
 +
 +
The '''Project''' menu replaces the '''Administration''' menu when you are editing an app project. To return to the '''Administration''' menu, use the back (arrow left) button in the top left corner of the application.
 +
 +
Components
 
* [[Home screen]]
 
* [[Home screen]]
 +
* [[Entity hubs]]
 
* [[Dashboard]]
 
* [[Dashboard]]
 
* [[Social]]
 
* [[Social]]
 +
* [[Offline HTML]]
 +
* [[Process]]
 +
* [[Timeline]]
 +
 +
Design
 
* [[Branding]]
 
* [[Branding]]
* [[Auditing]]
+
* [[Theme]]
* [[Location tracking]]
 
 
* [[Images]]
 
* [[Images]]
* [[Offline HTML]]
 
 
* [[Localization]]
 
* [[Localization]]
* [[Configuration]]
+
 
 +
Map & Routes
 
* [[Global map]]
 
* [[Global map]]
 +
* [[Route plan]]
 +
* [[Location tracking]]
 +
* [[Opening hours]]
 +
 +
PIM
 
* [[Calendar]]
 
* [[Calendar]]
* [[Route plan]]
 
* [[Voice control]]
 
 
* [[Schedule Board]]
 
* [[Schedule Board]]
* [[Entity hubs]]
 
 
* [[Events and reminders]]
 
* [[Events and reminders]]
* [[Theme]]
 
* [[Documents]]
 
 
* [[Exchange]]
 
* [[Exchange]]
 
* [[Google]]
 
* [[Google]]
* Inspections
+
 
 +
Settings
 +
* [[Configuration]]
 +
* [[Voice control]]
 +
* [[Auditing]]
 +
* [[Documents]]
 +
* [[AI Image Recognition]]
 +
* [[Inspections]]
 +
* [[Process Flow]] (Dynamics only)
 +
* [[Houston video calls|Houston]]
 +
 
 +
Entities
 +
* List of entities available on your server.
  
 
== Managing entities ==
 
== Managing entities ==
  
All entities available in your back-end system are displayed in the '''Project''' menu. Some entities are grayed out, disabled. Disabled entities are invisible and unavailable in the mobile apps (both online and offline mode).
+
All entities available in your backend system are displayed in the '''Project''' menu. Some entities are grayed out, disabled. Disabled entities are invisible and unavailable in the mobile apps (both online and offline mode).
 
* To show or hide unavailable entities, toggle the phone button next to the search bar.
 
* To show or hide unavailable entities, toggle the phone button next to the search bar.
 
* To make an entity available in your projects, select it and click '''Enable'''. You can modify its properties, then click '''Save'''.
 
* To make an entity available in your projects, select it and click '''Enable'''. You can modify its properties, then click '''Save'''.
  
; Permission: You can set the Read, Write, Create and Delete permissions for the whole entity.
+
[[File:Managing entities and fields in woodford.png|600px]]
 +
 
 +
; Permission: You can set the Read, Write, Create, and Delete permissions for the whole entity.
 
:Permissions can be also configured individually on each field, see [[#Managing fields]] below.
 
:Permissions can be also configured individually on each field, see [[#Managing fields]] below.
  
 
; Mode: Select whether the data is available offline.
 
; Mode: Select whether the data is available offline.
:* If set to Online & Offline mode, the CRM data will be available in both Online and Offline mode. For Offline mode, the app will synchronize the entity records, upload user changes made in Mobile CRM app and download changes from the server. In Online mode, user will have access to CRM records based on the set view filters.
+
:* If set to Online & Offline mode, the CRM data is available in both online and offline mode. For offline mode, the app synchronizes the entity records: uploads user changes made in the Mobile CRM app and downloads changes from the server. In online mode, users have access to server records based on the configured view filters.
:* If set to Online only mode, Online mode will work as in the previous option. In Offline mode however, no records will be downloaded from CRM server and even if user creates a new record, it will not be uploaded. Basically, this option sets the synchronization process to completely ignore the entity.
+
:* If set to Online only mode, the online mode continues to function as in the previous option. In offline mode, however, no records are downloaded from backend server, and even if a user creates a new record, the record cannot be uploaded. Basically, this entity is completely ignored by the synchronization process.
 +
:: To avoid the creation of records in offline mode, it is possible to create a simple '''On Load''' rule for the entity form (Conditions: If Configuration.isonline equals True; Step: IsFormEditable equals False)
 +
 
 +
; Synchronization: Select how this entity should be synchronized after it has been successfully synchronized at least once. (The initial entity sync always behaves in the same way: it downloads all records matching the sync filter.)
 +
:* Standard Sync: This is the default option. The app downloads all changed records from the server.
 +
:* Always Full Sync: The app downloads all entity records (as if it was never synced before). In rare cases, performing full sync might be more efficient than the standard algorithm. However, in most cases, full sync increases synchronization time; sometimes dramatically. ([[Synchronization_steps#When_to_use_Always_Full_Sync_for_an_entity.3F|When to use Always Full Sync?]])
 +
:* [[Sync_Filter#Incremental_linked_sync_filters|Incremental with Sync Filter]]: The app downloads all changed records that match the sync filter. This can save a lot of network traffic. However, the risk is that client might not get the information that some server records stopped matching the sync filter. This option works best for immutable records.
 +
 
 +
: Note: [[Synchronization_steps#SyncAnalyzer|SyncAnalyzer]] can override the above setting by enforcing full sync for performance reasons. You can switch off SyncAnalyzer using Woodford [[configuration]] ('''Disable Sync Analyzer''').
  
; Synchronization: Select how this entity should be synchronized. See [[Synchronization]] for more information.
+
; On Conflict: Conflict appears when the same record is changed on the device and before being synchronized, a change occurs on the CRM server (e.g. other user changes the same record and synchronizes changes before the first user, or the record is changed on the CRM server). See [[conflict resolution]] for details.
:* Standard Sync
 
:* Always Full Sync
 
:* Incremental with Sync Filter
 
  
; On Conflict: Conflict appears when the same record is changed on the device and before being synchronized, a change occurs on the CRM server (e.g. other user changes the same record and synchronizes changes before the first user, or the record is changed on the CRM server).The [[conflict resolution]] strategy is as following:
+
; Upload Status with Data {{Anchor|update_status}}: This option controls how changes in the state/status fields are uploaded to the backend server during synchronization. The default behavior is that status fields for some entities are uploaded separately, after the regular fields. When you select this option, all entity fields including status are uploaded in one pass. See [[Synchronization_steps#Special_considerations|the description of the upload step]] for more information.
:* Server Wins – When there is a conflict, server version of the record is used and overwrites the record on the client.
 
:* Device Wins – Since only changed fields are sent to CRM server, when there is a conflict, the server and client records are “merged”, because only changed fields that are sent to server are overwritten by client version.
 
:* Manual Action – When there is a conflict, user receives a Sync Error, where he has multiple options how to deal with the error, e.g. edit the record on the device, save it and synchronize the changes again to beat the server change (Clear Error and retry).
 
:* Device Wins (Full) – Mobile CRM app sends and overwrites all fields to CRM server, even those that were not changed by the Mobile CRM app user.
 
:* These are also options that User Action offers: [https://www.resco.net/sync-errors/ LINK], plus, it is possible to take server version. For this, user needs to have access to the CRM server and the record is overwritten by the record from the server.
 
  
 
; Include Lookup Labels: When checked, the app no longer shows data related to that entity as “Unknown” in the offline mode. This often happened with ownerIDs of records, as the data with User names is stored in the User entity (by default the Owner entity is not enabled in Woodford).
 
; Include Lookup Labels: When checked, the app no longer shows data related to that entity as “Unknown” in the offline mode. This often happened with ownerIDs of records, as the data with User names is stored in the User entity (by default the Owner entity is not enabled in Woodford).
  
; Incremental Linked SyncFilter: Incremental Linked Sync Filter ensures that the linked filters on entities are checked during Incremental Synchronization. You can enable or disable it per entity, or use project default.
+
; [[Sync_Filter#Incremental_linked_sync_filters|Incremental Linked SyncFilter]]: Incremental Linked Sync Filter ensures that the linked filters on entities are checked during Incremental Synchronization. You can enable or disable it per entity, or use project default.
 +
 
 +
=== Salesforce-only parameters ===
 +
 
 +
; Synchronize linked files: Select which Salesforce files related to this object should be available offline.
 +
:* '''Owned and shared''': Only files that are created or explicitly shared with the user logged into the app are available offline.
 +
:* '''All''': Make all Salesforce files related to this object available offline.
 +
: This setting can have a considerable impact on sync performance and [[API calls|API count]], especially when enabled for an object with a large number of records. After enabling this option, full sync is needed on all mobile devices.
 +
 
 +
; Synchronize entity feed: Required for each object where you want to use [[chatter]]. This option is selected automatically when you add a chatter tab to any [[form]] of that object.
  
{{Note|Sync Filter allows you to limit the number of records downloaded into the offline storage on user devices. See [[Sync Filter]] for more information.}}
+
; Sync shared records: Enable this option if you want to properly [[Shared records#Salesforce|synchronize recently shared and unshared records during incremental sync]].
 +
 
 +
=== Toolbar functions ===
 +
 
 +
; Sync Filter: [[Sync Filter]] allows you to limit the number of records downloaded into the offline storage on user devices.
 +
; Edit Index: Create indexes to optimize the performance of the application by speeding up offline queries.
  
 
=== Managing fields ===
 
=== Managing fields ===
  
After enabling an entity, you can select fields that you plan to use on this entity in the Resco Mobile CRM application. For example, you can pick some additional fields you want to use in your mobile project: City, Country/Region, Street and ZIP/Postal Code. Here you can also enable the custom fields for the entity.
+
After enabling an entity, you can select fields that you plan to use on this entity in Resco mobile apps.
 +
* To enable a field, select the checkbox in the field's row and click '''Save'''.
 +
* To disable a field, clear the checkbox in the field's row and click '''Save'''.
 +
* Some fields are mandatory and cannot be disabled.
  
{{Note|Best practice: We recommend not to include too many entities and fields in your mobile project. CRM servers often include a large wealth of entities and fields, and most organizations only use a small subset. An even smaller subset of the data is necessary in the field. [[Sync Filter]] can further restrict which records should be downloaded to the mobile device. Careful planning can improve the performance of the app and satisfaction of the users.|Tip}}
+
For example, you can pick some additional fields you want to use in your mobile project: City, Country/Region, Street and ZIP/Postal Code. Here you can also enable the custom fields for the entity. You cannot create custom fields here; this must be done on the backend server.
  
You can also configure some properties for each field. Select a row and modify the '''Properties''' pane on the right.
+
{{Note|Best practice: We recommend not to include too many entities and fields in your mobile project. Backend servers often include a large wealth of entities and fields, and most organizations only use a small subset. An even smaller subset of the data is necessary in the field. [[Sync Filter]] can further restrict which records should be downloaded to the mobile device. Careful planning can improve the performance of the app and satisfaction of the users.|Tip}}
 +
 
 +
[[File:Properties pane for entity fields.png|right]]
 +
You can also configure some properties for each field. Select a row and modify the '''Properties''' pane on the right. Some parameters are read-only.
  
 
; Permissions: Configure the permissions to Read, Create, or Update values in the field.
 
; Permissions: Configure the permissions to Read, Create, or Update values in the field.
  
 
; Formatting: Affects the appearance of the fields in the forms.
 
; Formatting: Affects the appearance of the fields in the forms.
:* Single line – Field is formatted to have the appearance of a single line field in the mobile app.
+
:* Single line – Field is formatted to have the appearance of a single-line field in the mobile app.
:* Multiline – Field will have an appearance of a multiline field.
+
:* Multiline – Field will have the appearance of a multiline field.
 
:* Email – Adds an action button to the field in the mobile app, activation of which will provide user with an opportunity to immediately create an email.
 
:* Email – Adds an action button to the field in the mobile app, activation of which will provide user with an opportunity to immediately create an email.
 
:* Phone number – Field gets an action button that provides phone call functionality (the device will dial the number contained in the field).
 
:* Phone number – Field gets an action button that provides phone call functionality (the device will dial the number contained in the field).
 
:* URL – Adds an action button to open the URL in the native browser of the device.
 
:* URL – Adds an action button to open the URL in the native browser of the device.
:* Barcode – Adding an action button that activates a camera so user can scan [[Barcode]]s and [[QR code]]s. Function will only work on devices that have a camera with Autofocus.
+
:* Barcode – Adding an action button that activates a camera so user can scan [[Barcode]]s and [[QR code]]s. This function will only work on devices that have a camera with Autofocus.
:* HTML – Formats the text field into a HTML type (bodies of email, signatures and etc).
+
:* HTML – Formats the text field into an HTML type (bodies of email, signatures and etc).
:* DropDown, DropDownList, Multi DropDown, Multi DropDownList – this feature allows you to predefine input for users, so instead of entering a value, they can choose to use options from drop down list (or enter what is needed manually). More about this feature is shown in this [https://youtu.be/9vL4QRN_1dk?t=34m3s webinar section]. {{Badge|Webinar}}
+
:* DropDown, DropDownList, Multi DropDown, Multi DropDownList – this feature allows you to predefine input for users, so instead of entering a value, they can choose to use options from a drop-down list (or enter what is needed manually). See [[Localization_examples#Drop-down_options_for_text_input_fields|detailed instructions]] or watch this [https://youtu.be/9vL4QRN_1dk?t=34m3s webinar section]. {{Badge|Webinar}}
  
{{Note|If you disable any previously enabled field, please check all existing views and forms and remove any fields or lists marked by the sign “Invalid”, or enable the correspond field so that the field will no longer be listed as invalid. If there are any invalid fields or lists in the form or view, the application will crash when you try to open an entity list or record details. See [[Metadata changes in live projects]] for more information.|Warning}}
+
; Requirement Level
 +
:* A field can be either optional ("None") or required ("SystemRequired").
 +
 
 +
; Options
 +
:* For option/status fields, the available values are listed here.
 +
 
 +
; Default
 +
:* The default value of the field.
 +
 
 +
; Constraints
 +
:* For numbers, see the minimum and maximum allowed value. For strings, see the maximum size.
 +
 
 +
; Precision
 +
:* For floating-point numbers, see the maximum allowed precision.
 +
 
 +
; Lookup Targets
 +
:* For lookup fields, this parameter lists the allowed targets of the lookup.
 +
 
 +
; Advanced {{Anchor|Mark as Parent Pointer}}
 +
:* Mark as Parent Pointer – When you enable this flag for a lookup field, you can establish a child-parent relationship between entities. This information is used at various places in the app, for example, during synchronization to establish the order of entities when [[Synchronization_steps#Uploading_local_changes|uploading local changes]], when deleting parent entity records (to clean up also child records), in [[Sync Filter]] (to ensure that both parent and child records are available), etc.
 +
:: (Salesforce only) Check to download only attachments belonging to records that are available offline. This property can optimize data download.
 +
 
 +
; Description
 +
:* Description of the field.
 +
 
 +
{{Note|If you disable any previously enabled field, please check all existing views and forms and remove any fields or lists marked by the sign “Invalid”, or enable the corresponding field so that the field will no longer be listed as invalid. If there are any invalid fields or lists in the form or view, the application will crash when you try to open an entity list or record details. See [[Metadata changes in live projects]] for more information.|Warning}}
  
 
== User interface components ==
 
== User interface components ==
Line 168: Line 289:
 
* [[Home screen]]
 
* [[Home screen]]
 
* [[View]]
 
* [[View]]
* [[Form]]
+
* [[Form]] / [[Flexible form]]
 
* [[Hub]]
 
* [[Hub]]
* [[Flexible form]]
+
* [[Calendar]]
 +
* [[Map]]
 
* [[Dashboard]]
 
* [[Dashboard]]
  
 
Views, forms, and charts are defined for each entity. Select an entity in the '''Project''' menu and click '''Show UI''' to display a list of existing components.
 
Views, forms, and charts are defined for each entity. Select an entity in the '''Project''' menu and click '''Show UI''' to display a list of existing components.
 +
 +
[[File:Mobile views forms and charts.png|600px]]
 +
 +
Use the toolbar buttons to manage views, forms, and charts.
 +
* '''Show Fields''' / '''Show UI''': Toggle between entity settings and entity UI.
 +
* '''New View''', '''Special View''', '''New Chart''', '''New Form''': Create a new UI component for the selected entity.
 +
* '''Clone''': Create a copy of the selected UI component.
 +
* '''Select Form''': If you have multiple forms defined for an entity, configure [[Form#What_form_is_used.3F|what form is used when]].
 +
* '''Edit''': Change the design of the selected component.
 +
* '''Properties''': Edit the properties of the selected component.
 +
* '''Delete''': Delete the selected component.
 +
* '''Restore''': Restore the selected component to the version inherited from the parent project. See [[App_projects#Project_hierarchy|project hierarchy]] for more information.
 +
* '''Import File''' / '''Export File''': Use these functions to transfer UI components between app projects.
 +
* '''Import Form''' / '''Import Views''' (Salesforce only): Import UI components (page layouts and views) from the Salesforce server.
  
 
== Custom images, colors, brands, and more ==
 
== Custom images, colors, brands, and more ==
Line 183: Line 319:
 
* [[Localization]]
 
* [[Localization]]
 
* [[Theme]]
 
* [[Theme]]
 +
 +
== Notifications ==
 +
 +
Use [[Entity notification workflow]] to trigger an automatic notification when an entity record is created or modified.
  
 
[[Category:Woodford]]
 
[[Category:Woodford]]

Latest revision as of 14:53, 30 June 2021

An app project is a customized version of the mobile application dedicated to a particular set of users. Or more precisely, the application remains the same, but each project may have a different set of data and functions available.

Administrators use Woodford to create various projects and publish them. App users synchronize their mobile app to access the necessary functions and data.

What's an app project

App projects are defined by three main blocks:

App projects are represented as a set of metadata. The customizations are saved on the backend server.

  • For installations with Microsoft Dynamics, app projects are saved directly in Microsoft Dynamics.
  • For installations with Salesforce and Resco Cloud, app projects are saved in Resco Cloud.

App projects are designed for a particular user role. For example, you can create one project for field technicians and a different one for the manager.

Grouping app projects

Optionally, you can group app projects into apps. Each project belongs to a group. Users of Resco mobile apps can then switch between apps.

You can create app groups when creating a new app project or when editing the properties of an existing app project: Set the App to "Create a new app..." and enter a New App Name.

To delete an app group, simply remove all app projects from the group, either by assigning them to a different app group or by deleting them.

Project properties

Select App Projects from the Administration menu of Woodford to display a list of existing projects. The following project properties are displayed in the list:

App group
App projects can be grouped into apps. If you don't use this feature, all projects are in a single group called "Default". You can set the app group when creating the app project and modify it using the Properties button > App field.
Icon
The icon offers a visual clue about the state of projects.
  • Active project.png Green check mark: The latest version of the project has been published.
  • Draft project.png Grey exclamation mark: If a project has a grey icon with an exclamation mark, it means the project is dirty, i.e. there has been a change in the project but it was not published after making these changes.
  • Inactive project.png Red no-entry sign: Project has been deactivated.
Name
You can enter any name for your project. As you create more projects, an intuitive name will help you identify them.
Priority
When you create more projects for the same security role, the one with a higher priority is used.
  • For example, if you create two mobile projects for a role Salesperson, one with the priority number 10 and second with 100, the second one will be used when the application synchronizes (since it has a higher priority number).
  • The same principle applies when a user has multiple security roles assigned and there are mobile projects created for these roles.
Parent
Name of the parent project; see #Project hierarchy below.
Published on
Date and time of the last successful publishing of a project.
Type
For internal CRM users (usually employees), use Standard User. See External users for information about the other options.
Format
Format 1 (Packed) means that the project was created and used by Silverlight Woodford. The project is stored in CRM as a Note attachment associated to a Mobile Project record. When a Format 1 project is opened using HTML Woodford, the project is updated to Format 2. We recommend exporting Format 1 projects before opening them in Woodford HTML.
Format 2 means that the project was opened or created using HTML Woodford. It is no longer stored as a Note attachment; each project file is stored as a record in Mobile Project Item entity. This allows multiple users to work concurrently on the same project (on different parts of the project), and prevents projects from accidental corruption, e.g. due to bulk deletion of notes or using cloud storage for note attachments. Format 2 projects can still be opened using Silverlight Woodford, however, HTML Woodford is necessary to publish them.
Note HTML version of Woodford can only delete Format 2 projects. Usually, the upgrade from Format 1 to Format 2 happens seamlessly, when you open a Format 1 project. If you are cleaning up old projects and you attempt to delete a Format 1 project, this will fail. Open the project and save it immediately; then you can delete it.

Additional properties are available when you create projects:

Roles
Select one or more security roles (or profiles in Salesforce) for which you want to create the project. You can create different app projects for different users based on their roles (profiles).
Template
Select one of the pre-defined app templates, such as sales or field service. Templates come with a pre-configured home screen and defined lists and views designed for a particular use case.
Custom Version Identifier (Optional)
Enter an optional text that identifies this particular project version. This information is displayed in the app.

Toolbar functions

The following buttons and options are available when working with the list of app projects.

New
Create a new project.
Edit
Select a project and modify it. Alternatively, you can simply double-click a project.
Properties
Modify the project's properties: Name, Role, and Priority.
Show Users
Display the list of users who receive the customization, i.e., users with a security role that's assigned to this project.
Delete
Delete the project.
Activate
Activate a previously deactivated project.
Deactivate
Deactivate a project. New mobile users cannot use inactive projects. Existing users can continue using it.
Import
Import a previously exported project.
Export
Save a copy of the project to your local computer. This can be useful for backup.
Clone
Create a copy of the selected project. You must enter a new Name, Role, and Priority. Cloning is useful when you want to duplicate a project for different users or when you want to experiment with Woodford and you don't want to lose your current project.
Restore
Return to the last published version of the selected project. If you accidentally delete Resco Mobile project’s note (or its attachment), which leads to losing your project and there is no backup, you can use the Restore button. It will create the project’s note and attachment from the last published version of the project. Only changes made after publishing will be lost and you don’t have to rebuild the project from scratch.
Recover
If you for example accidentally destroy your CRM organization and recover it without Resco entities, it is possible to recover the project from data synced on the Windows device. In case such a situation happens, please contact us on mobilecrm@resco.net for further steps, from which the last one is using the Recover button.
Derive
Creates a child project.
Flatten
Makes a standalone project from a derived project ("flattens" the hierarchy)
Check User
Specify a user name to display a list of all app projects where a user is involved, including project priority, so that you can see which customization is used.
Commit
Sends project changes to GitHub
Checkout
Retrieves project changes from GitHub
Configure
Configures GitHub connection
Update
(Salesforce) Downloads metadata from Salesforce.

Once you open an app project for editing, you can use the following buttons and options.

Publish, Publish All
Once you are done editing an app project and you would like to push your changes to the mobile users, you need to publish your project. Next time your app users synchronize their apps, the customization will be applied on their devices. See Publishing app projects for more information.
Validate
Verify if your changes to the app project have not broken anything. Validation is also performed automatically before each publishing.
Publish Version
Use the latest version, unless you know that your users have an old version of the app.
Commit
Send project changes to GitHub. See GitHub integration for more information.

Additional controls may become available once you select a function from the Project menu.

Project hierarchy

You can establish a parent/child relation between your projects. Child projects inherit all changes from the parent project except for the parts changed directly in the child project.

Here are the basic principles of how this functions:

  • Creating a child project creates essentially an empty project with a reference to the parent project, because it uses the project files of the parent project.
  • When you modify a setting or component in the parent project, and the child project does not have its own definition of the component, parent change is used.
  • When you modify a setting or component in the child project, the link to the parent is permanently broken for that component. Any further changes for the component in the parent no longer apply to the child.
  • Behind the scenes, project components are saved as files. For example, Sync Filter is stored as a single file. If you modify the sync filter in the child project, further changes in the parent will no longer be inherited.
  • In Woodford, many project components include the State column, indicating whether a component is inherited from the parent or overridden by the child.
    Inherited or overridden.png
  • You can use the Publish All button to publish the selected parent project including its all derived projects in a single click.

See also:

  • For more information about the project hierarchy, please check this section of one of our webinars. Webinar
  • For information about the child project’s parts, whether they are inherited or changed in the child project, please check this additional webinar. Webinar
  • Woodford project hierarchy Blog

Merge child changes to parent

The Flatten function allows you to merge changes in the child project into its parent.

For example, imagine three projects in a hierarchy:

  • Parent
    • Child
      • Grandchild

Continuing with this example, if you click Flatten on the project in the lowest level (in this case, the grandchild), all changes from the entire child hierarchy are merged into the highest project (in this case, the parent) and will result in a standalone project, when you will be given two options: export the project or create it as new one, free of any previous parent project reference.

The merge is perfomed in a cascade, all changes made in the grandchild project are merged into the child project and then into the parent project. Depending on whether you’ve made changes in both child projects on the same item, the changes from the grandchild overwrite changes in the child.

Before flattening the projects, please remember to back up all projects you wish to merge. Remember that sync filters of all entities are joined into one file, therefore, if you changed the grandchild's sync filter, flattening will overwrite sync filters in the child and parent project.

Project menu

The Project menu in the left pane of Woodford allows you to access various functions and settings related to app projects, as well as all entities available in the backend.

Project menu filtering.png The top row of the menu serves you to simplify navigation:

  • Search: Use to quickly filter menu items. The search is not case-sensitive.
  • Disabled entities: Toggle to show or hide disabled entities.
  • Favorites: Click to show only menu items that you marked as favorite.
  • Expand/collapse all: Expand or collapse all submenus.

The Project menu replaces the Administration menu when you are editing an app project. To return to the Administration menu, use the back (arrow left) button in the top left corner of the application.

Components

Design

Map & Routes

PIM

Settings

Entities

  • List of entities available on your server.

Managing entities

All entities available in your backend system are displayed in the Project menu. Some entities are grayed out, disabled. Disabled entities are invisible and unavailable in the mobile apps (both online and offline mode).

  • To show or hide unavailable entities, toggle the phone button next to the search bar.
  • To make an entity available in your projects, select it and click Enable. You can modify its properties, then click Save.

Managing entities and fields in woodford.png

Permission
You can set the Read, Write, Create, and Delete permissions for the whole entity.
Permissions can be also configured individually on each field, see #Managing fields below.
Mode
Select whether the data is available offline.
  • If set to Online & Offline mode, the CRM data is available in both online and offline mode. For offline mode, the app synchronizes the entity records: uploads user changes made in the Mobile CRM app and downloads changes from the server. In online mode, users have access to server records based on the configured view filters.
  • If set to Online only mode, the online mode continues to function as in the previous option. In offline mode, however, no records are downloaded from backend server, and even if a user creates a new record, the record cannot be uploaded. Basically, this entity is completely ignored by the synchronization process.
To avoid the creation of records in offline mode, it is possible to create a simple On Load rule for the entity form (Conditions: If Configuration.isonline equals True; Step: IsFormEditable equals False)
Synchronization
Select how this entity should be synchronized after it has been successfully synchronized at least once. (The initial entity sync always behaves in the same way: it downloads all records matching the sync filter.)
  • Standard Sync: This is the default option. The app downloads all changed records from the server.
  • Always Full Sync: The app downloads all entity records (as if it was never synced before). In rare cases, performing full sync might be more efficient than the standard algorithm. However, in most cases, full sync increases synchronization time; sometimes dramatically. (When to use Always Full Sync?)
  • Incremental with Sync Filter: The app downloads all changed records that match the sync filter. This can save a lot of network traffic. However, the risk is that client might not get the information that some server records stopped matching the sync filter. This option works best for immutable records.
Note: SyncAnalyzer can override the above setting by enforcing full sync for performance reasons. You can switch off SyncAnalyzer using Woodford configuration (Disable Sync Analyzer).
On Conflict
Conflict appears when the same record is changed on the device and before being synchronized, a change occurs on the CRM server (e.g. other user changes the same record and synchronizes changes before the first user, or the record is changed on the CRM server). See conflict resolution for details.
Upload Status with Data
This option controls how changes in the state/status fields are uploaded to the backend server during synchronization. The default behavior is that status fields for some entities are uploaded separately, after the regular fields. When you select this option, all entity fields including status are uploaded in one pass. See the description of the upload step for more information.
Include Lookup Labels
When checked, the app no longer shows data related to that entity as “Unknown” in the offline mode. This often happened with ownerIDs of records, as the data with User names is stored in the User entity (by default the Owner entity is not enabled in Woodford).
Incremental Linked SyncFilter
Incremental Linked Sync Filter ensures that the linked filters on entities are checked during Incremental Synchronization. You can enable or disable it per entity, or use project default.

Salesforce-only parameters

Synchronize linked files
Select which Salesforce files related to this object should be available offline.
  • Owned and shared: Only files that are created or explicitly shared with the user logged into the app are available offline.
  • All: Make all Salesforce files related to this object available offline.
This setting can have a considerable impact on sync performance and API count, especially when enabled for an object with a large number of records. After enabling this option, full sync is needed on all mobile devices.
Synchronize entity feed
Required for each object where you want to use chatter. This option is selected automatically when you add a chatter tab to any form of that object.
Sync shared records
Enable this option if you want to properly synchronize recently shared and unshared records during incremental sync.

Toolbar functions

Sync Filter
Sync Filter allows you to limit the number of records downloaded into the offline storage on user devices.
Edit Index
Create indexes to optimize the performance of the application by speeding up offline queries.

Managing fields

After enabling an entity, you can select fields that you plan to use on this entity in Resco mobile apps.

  • To enable a field, select the checkbox in the field's row and click Save.
  • To disable a field, clear the checkbox in the field's row and click Save.
  • Some fields are mandatory and cannot be disabled.

For example, you can pick some additional fields you want to use in your mobile project: City, Country/Region, Street and ZIP/Postal Code. Here you can also enable the custom fields for the entity. You cannot create custom fields here; this must be done on the backend server.

Tip Best practice: We recommend not to include too many entities and fields in your mobile project. Backend servers often include a large wealth of entities and fields, and most organizations only use a small subset. An even smaller subset of the data is necessary in the field. Sync Filter can further restrict which records should be downloaded to the mobile device. Careful planning can improve the performance of the app and satisfaction of the users.
Properties pane for entity fields.png

You can also configure some properties for each field. Select a row and modify the Properties pane on the right. Some parameters are read-only.

Permissions
Configure the permissions to Read, Create, or Update values in the field.
Formatting
Affects the appearance of the fields in the forms.
  • Single line – Field is formatted to have the appearance of a single-line field in the mobile app.
  • Multiline – Field will have the appearance of a multiline field.
  • Email – Adds an action button to the field in the mobile app, activation of which will provide user with an opportunity to immediately create an email.
  • Phone number – Field gets an action button that provides phone call functionality (the device will dial the number contained in the field).
  • URL – Adds an action button to open the URL in the native browser of the device.
  • Barcode – Adding an action button that activates a camera so user can scan Barcodes and QR codes. This function will only work on devices that have a camera with Autofocus.
  • HTML – Formats the text field into an HTML type (bodies of email, signatures and etc).
  • DropDown, DropDownList, Multi DropDown, Multi DropDownList – this feature allows you to predefine input for users, so instead of entering a value, they can choose to use options from a drop-down list (or enter what is needed manually). See detailed instructions or watch this webinar section. Webinar
Requirement Level
  • A field can be either optional ("None") or required ("SystemRequired").
Options
  • For option/status fields, the available values are listed here.
Default
  • The default value of the field.
Constraints
  • For numbers, see the minimum and maximum allowed value. For strings, see the maximum size.
Precision
  • For floating-point numbers, see the maximum allowed precision.
Lookup Targets
  • For lookup fields, this parameter lists the allowed targets of the lookup.
Advanced
  • Mark as Parent Pointer – When you enable this flag for a lookup field, you can establish a child-parent relationship between entities. This information is used at various places in the app, for example, during synchronization to establish the order of entities when uploading local changes, when deleting parent entity records (to clean up also child records), in Sync Filter (to ensure that both parent and child records are available), etc.
(Salesforce only) Check to download only attachments belonging to records that are available offline. This property can optimize data download.
Description
  • Description of the field.
Warning If you disable any previously enabled field, please check all existing views and forms and remove any fields or lists marked by the sign “Invalid”, or enable the corresponding field so that the field will no longer be listed as invalid. If there are any invalid fields or lists in the form or view, the application will crash when you try to open an entity list or record details. See Metadata changes in live projects for more information.

User interface components

Use the following building blocks to create your application:

Views, forms, and charts are defined for each entity. Select an entity in the Project menu and click Show UI to display a list of existing components.

Mobile views forms and charts.png

Use the toolbar buttons to manage views, forms, and charts.

  • Show Fields / Show UI: Toggle between entity settings and entity UI.
  • New View, Special View, New Chart, New Form: Create a new UI component for the selected entity.
  • Clone: Create a copy of the selected UI component.
  • Select Form: If you have multiple forms defined for an entity, configure what form is used when.
  • Edit: Change the design of the selected component.
  • Properties: Edit the properties of the selected component.
  • Delete: Delete the selected component.
  • Restore: Restore the selected component to the version inherited from the parent project. See project hierarchy for more information.
  • Import File / Export File: Use these functions to transfer UI components between app projects.
  • Import Form / Import Views (Salesforce only): Import UI components (page layouts and views) from the Salesforce server.

Custom images, colors, brands, and more

Apps created from the building blocks can be further customized to better match your corporate design:

Notifications

Use Entity notification workflow to trigger an automatic notification when an entity record is created or modified.