vb-process-local

Processes application sources locally in the Grunt process.

The processing operation resolves various templates and further modifies (adds and updates) several application resources.

To run this task, you must provide the Visual Builder URL and your credentials for accessing the Visual Builder instance. You can provide the credentials directly when you run the task. Alternatively, you can use the accessToken option to specify a valid OAuth access token. If you provide both credentials and an OAuth access token, the task authenticates using the access token.

The following table describes the subtasks, hooks, and inputs and outputs of the vb-process-local task:

Detail	Description
subtasks	n/a
multitask	n/a
hooks	n/a
input	`${gitSources}`
output	`build/processed/*`

The following tables describe the options for the vb-process-local task. The :ce suffix is required only when your application includes Web Components and, as a result, references the Component Exchange.

Authentication options

Name	Mandatory	Default Value	Description
url[:ce]	no	n/a	URL of the Component Exchange service. Not needed if the application does not reference Web Components. Talk to your administrator to get the URL of the Component Exchange used by your Visual Builder instance, available on the Tenant Settings page. For the URLs of publicly available Component Exchanges, see Manage Your Component Exchange in Administering Oracle Visual Builder Generation 2.
username[:ce]	no	n/a	The username to access the Component Exchange service. The `:ce` suffix is optional.
password[:ce]	no	n/a	The password to access the Component Exchange service. The `:ce` suffix is optional. A password specified via the `--password` Grunt option may need to be enclosed in single quotation marks (') if it contains special characters. In general, it's advisable to always use quotation marks for the `--password` option, especially in VB Studio jobs where the password is provided via a job variable. For example: `grunt vb-deploy '--password=Jkl@#&!%^23' ...`. Here's an example of the `vb-process-local` task with the `--username` and `--password` options when your app is using components from the publicly available Component Exchange: `grunt vb-process-local --url:ce=https://devinstance4wd8us2-wd4devcs8us2.uscom-central-1.oraclecloud.com/profile/devinstance4wd8us2-wd4devcs8us2/s/devinstance4wd8us2-wd4devcs8us2_compcatalog_3461/compcatalog/0.2.0 --username:ce=comp.catalog --password:ce=bXwphh6RMFjn#g`
accessToken[:ce]	no	n/a	The value of an OAuth access token to access the Component Exchange service. If provided, username and password options are not necessary. The `:ce` suffix is optional.

Build options

Name	Mandatory	Default Value	Description
target	no	build	Name of build directory.
git-sources	no	./	Location of the visual application's sources.

Other options

Name	Mandatory	Default Value	Description
mode	no	default	Defines the build mode: default: Builds a visual application's assets for deployment to Visual Builder runtime service fa: Builds a visual application's assets for deployment to an Oracle Cloud Applications environment
fa-indexHtml-resolveVariables	no	true	When `mode=fa` and if this property is set to `false`, the generated `index.html` does not resolve JET and VB URL and version template variables. The file will contain %JET_CDN_PATH%, etc.
fa-inject-pwa-tokens	no	false	When `mode=fa`, the build injects the following tokens into `index.html` `<!-%APPLE_ICONS_LINKS%> <!%SPLASHSCREENS_LINKS%->` Oracle Cloud Applications servlet should resolve these tokens in the runtime.
enableTelemetry	no	false	Injects the Trace.ConsoleProfile initializer into the generated `index.html`

You can better control the template-resolving process for the web (or mobile) application's index.html using the fa build mode rather than the default build mode. Resolving the following templating marks:

can be controlled by the following template variables, defined in the configuration of the vb-process-local task:

%BASE_URL%
%JET_CDN_PATH%
%JET_CDN_VERSION%
%VB_CDN_PATH%
%VB_VERSION%
%JET_UI_STYLE_PATH%

If the resolveTemplate configuration object is not provided for this task, these variables will be left unresolved in the resulting index.html.

If the resolveTemplate configuration object is set at least to an empty object, the template variables will be resolved with values taken from the application's version files (private/custom/versions.json or resources/package/versions.json), or with default values if none of these exist. The exception is the %BASE_URL% variable, which doesn't have a default and the template variable reference will be kept in the resulting index.html until the value is provided explicitly in the resolveTemplate configuration object, as in the following example:

grunt.initConfig({
  "vb-process-local": {
    options: {
      resolveTemplate: {
          BASE_URL: 'http://oracle.cloud/abc',
      }
    }
  },
});

The configuration object may also contain values for the other template variables. In such case, the configuration value has precedence before the versions files and defaults.

Setup to Resolve Environment Variables

The vb-process-local task creates static application assets that contain various environment variables, which are resolved when application assets are deployed to a Visual Builder runtime instance by the vb-deploy task. If you don't deploy the application to a Visual Builder instance, you may want to resolve these variables during the build. This may be handy, for example, for local application development which in combination with the vb-serve task allows you to quickly test your application locally.

You can define environment variable values by adding the following configuration to your Gruntfile.js file (you can also add the configuration into the object you pass to the grunt.initConfig() method call). Here's an example Gruntfile.js with the vb-process-local environment configuration:

grunt.config('vb-process-local.environment', {
       "env.userProfileUrl": "_currentuser",
       "env.vbServer.url": "http://127.0.0.1:3000/",
       "env.vbServer.context": "",
       "env.application.id": "myApp",
       "env.application.version": 1618840321144,
       "env.profileId": "base_configuration",
        });

The following table describes the list of environment variables used during the Grunt build process:

Name	Description
`app-flow.json`
env.profileId	Selected application profile
env.userProfileUrl	User profile URL
env.oauthUserProfileUrl	OAuth user profile URL
env.idcsInfo	IDCS information
`catalog.json`
env.catalogJson	Entire contents of the catalog.json file
`index.html`
env.vbServer.url	URL of the Visual Builder runtime server
env.vbServer.context	Context path of the Visual Builder runtime server
env.application.version	Application version