View source for App projects

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 [[Resco mobile apps|mobile app]] to access the necessary functions and data.

== What's an app project ==

App projects are defined by three main blocks:
* [[Data model in mobile apps|Data model]]
* [[#User interface components|User interface]]
* [[Business logic]]

App projects are represented as a set of metadata. The customizations are saved on the backend server.
* For installations with Microsoft Dynamics/Dataverse, app projects are saved directly in Dataverse.
* 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.

== Creating app projects ==

Start [[Woodford]] and select '''App Projects''' from the '''Administration''' menu to get started. You have several options for creating app projects:

* Click '''New''' to start the new app project wizard (described below).
* Click '''Import PowerApp''' to convert model-driven apps from your Power Platform or Dynamics organizations into Resco app projects. See [[Import Power Apps to Woodford]].
* Click '''Import''' to add a previously exported app project.
* Click '''Clone''' to create a new copy of an existing project.

[[File:App-project-list-in-woodford.png|600px]]

;New project wizard
# Select whether to create a standard project for internal users or a project for external users. For more information about external users, see [[External users]].
# Select one of the app project templates so you don't have to create the project from scratch.
# Select an app project group where to add your new project. Use the default option when in doubt.
# Enter additional details about the app project.

[[File:Create-new-project-wizard-part1.png|300px]] [[File:Create-new-project-wizard-part2.png|300px]] [[File:Create-new-project-wizard-part3.png|300px]] [[File:Create-new-project-wizard-part4.png|300px]]

== 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="180px" style="text-align:left;">
File:Apps and app projects.png|alt=List of app projects in groups|List of app projects in groups
File:App project properties.png|alt=Configure the App group in project properties|Configure the '''App''' group in project properties
File:Switch app from app.png|alt=Settings to change between apps|Go to [[Setup]]/Settings to change between apps 
File:Switch app from webapp.png|alt=In the web app, switch apps using the profile button|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 ==

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.
:* [[File:Active project.png|alt=active project icon]] Green check mark: The latest version of the project has been published.
:* [[File:Draft project.png|alt=draft project icon]] 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.
:* [[File:Inactive project.png|alt=inactive poject icon]] 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 {{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 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 your app project for some reason becomes corrupt, if you delete or misconfigure your vital settings, you can use the Restore button. It will create the app project 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 [https://resconet.atlassian.net/servicedesk/customer/portals support] 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)
; Dump: {{Preview|Export the app project in a format normally consumed by [[Resco Mobile CRM]] during [[Synchronization_steps#Download_app_project_from_backend_server|synchronization/customization update]]. When used on a child project, the export will include information from the parent project. Occasionally, Resco support may ask for this file.}}
; 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 integration|GitHub]]
; Checkout: Retrieves project changes from [[GitHub integration|GitHub]]
; 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.

; 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.<br>[[File:Inherited or overridden.png|alt=project state inherited/overriden|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:
* 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}}
* [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 ==

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.

[[File:Project menu filtering.png|alt=Project menu (left pane) filtering|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]]
* [[Entity hubs]]
* [[Dashboard]]
* [[Social]]
* [[Offline HTML]]
* [[Process]]
* [[Timeline]]
* [[Tree]]

;Design
* [[Branding]]
* [[Theme]]
* [[Style editor|Styles]]
* [[Images]]
* [[Localization]]

;Map & Routes
* [[Global map]]
* [[Route plan]]
* [[Location tracking]]
* [[Opening hours]]

;PIM
* [[Calendar]]
* [[Schedule Board]]
* [[Events and reminders]]
* [[Exchange]]
* [[Google]]

;Settings
* [[Configuration]]
* [[Data model explorer]]
* [[Voice control]]
* [[Auditing]]
* [[Documents]]
* [[AI Image Recognition]]
* [[Inspections]]
* [[Process Flow]] (Dynamics only)
* [[Houston video calls|AR Calls]]
* [[Guides]]

;Entities
* List of entities available on your server. Select the ones you want to make available in the mobile app.

== Managing entities ==

One of the first steps when designing app projects is to set up the data model. Select a subset of server entities and fields you want to make available on the mobile device. See [[Data model in mobile apps]] for more details.

== User interface components ==

Use the following building blocks to create your application:
* [[Home screen]]
* [[View]]
* [[Form]] / [[Flexible form]]
* [[Hub]]
* [[Calendar]]
* [[Map]]
* [[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.

[[File:Mobile views forms and charts.png|alt=Mobile views forms and charts|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 [[Select Form|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 ==

Apps created from the building blocks can be further customized to better match your corporate design:
* [[Branding]]
* [[Custom mobile apps]]
* [[Images]]
* [[Localization]]
* [[Theme]]

== Business logic ==

App projects can include custom [[business logic]] that direct the interaction between user interface and data, such as:
* [[Rules editor|No-code business logic using rules]]
* [[Resco JavaScript Bridge|HTML/JavaScript code that can interact with the user interface, with data, and perform additional actions]]
* [[Entity notification workflow]] for triggering automatic notifications when an entity record is created or modified.

[[Category:Woodford]]