ng-salesforce

Pre Installation

Prior to installing ng-salesforce, you must have access to a Salesforce org and have an @angular/cli application.

Installation

To install this library, run:

$ npm install ng-salesforce

During installation, you will be asked for a number of things to connect the application to your salesforce org.

and then from your Angular AppModule:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';

// Import your library
import { SalesforceModule } from 'ng-salesforce';

// salesforce.config.ts will be created during installation and saved at src/app/salesforce.config.ts
import { Configuration } from './salesforce.config';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,

    // Specify your ng-salesforce as an import
    SalesforceModule.forRoot(Configuration)
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Once your library is imported, you can use its components, directives and pipes in your Angular application:

Defining a model

Propert state management is crucial to a successful Angular PWA. To that end, accessing data within Salesforce requires you to define your model within a Typescript class. Behind the scenes, ng-salesforce is managing how your components access and interact with that data to avoid uncessary operations and maintain synchronicity.

Here's an example that defines the account and contact relationship for a component.

import { SObjectModel, SObject, ChildRecord } from 'ng-salesforce';

// We use the decorator SObjectModel to tell ng-salesforce this class maps to the 'Account' object
// In order to access standard sObject fields, our Account class must extend 'SObject'
// The class name can be anything, but the name property in the SObjectModel decorator must map to an object API name
@SObjectModel({name : 'Account'})             
export class Account extends SObject{         

  // Define the fields you would like in your object. The name of the field must map to a field API name in salesforce
  public Name: string = null;                 
  public IsCustomerPortal: boolean = null;
  public My_Custom_Field__c: number = null;

  //Related Lists
  public Opportunities: ChildRecord = new ChildRecord(new Opportunity())
}

@SObjectModel({name : 'Opportunity'})
export class Oppoortunity extends SObject{
  public Name: string = null;
  public AccountId: string = null;
}

@SobjectModel({name : 'Contact'})
export class Contact extends SObject{
  public Name: string = null;

  //Lookup
  public Account: Account = new Account();
}

Defining a Service

After defining your model, you can access the data by creating a service for the models. The SObjectService class contains many of the standard DML and query operations to access the data, however you may add any convenience methods you want to your service. The core service methods are usually very simple.

import { SObjectService, SObjectType } from 'ng-salesforce';
import { Injectable } from '@angular/core';
import { Account } from './account.model.ts'  // This is a reference to the account model created in the previous section


@Injectable({
    providedIn : 'root'
})
export class AccountService extends SObjectService{
  //Add service methods here
  type = Account;
}

Access the data in your component

import { Component, OnOnit } from '@angular/core';
import { AccountService } from './account.service.ts';
import { Account } from './account.model.ts';

@Component({
  selector : 'app-account',
  template : `

  `,
  styles : [``]
})
export class AccountComponent implements OnInit{
  
  constructor(private accountService: AccountService){}

  // Always perform service methods in the ngOnInit method
  ngOnInit(){
    this.accountService.where(`Id <> NULL LIMIT 1`).subscribe(res => {
      /*
      res === [
        {
          Name : 'Account A',
          IsCustomerPortal : false,
          My_Custom_Field__c : 1,
          Id : 'xxx',
          ...
          Opportunities : {
            totalSize : 1,
            records : [
              Name : 'Opportunity A',
              AccountId : 'xxx',
              Id : 'xxx',
              ...
            ]
          }
        }
      ]
      */
    });
    this.accountService.describe('My_Custom_Field__c', false).subscribe(res => {
      // Describe information for My_Custom_Field__c
    });

    this.accountService.search(`FIND 'map*' IN ALL FIELDS RETURNING Account (Id, Name)`).subscribe(res => {
      // SOSL Search Results
      // Note : search does not follow the model pattern and will return results specified in the query
    });

    this.accountService.get(['00Fxxxxxxx', '00Fxxxxxxx']).subscribe(res => {
      // Returns an array of account records
    })

    this.accountService.aggregate(`ID <> NULL`).subscribe(res => {
      // Returns aggregates for the specified clause. (i.e. total records as well as max/min values for all 
      // fields specified in the model)
    })

    this.accountService.create([new Account()]).subscribe(res => {
      // Returns list of id's created
    })
  
    this.accountService.update([new Account()]).subscribe(res => {
      // Returns list of id's updated
    })  

    this.accountService.upsert([new Account()]).subscribe(res => {
      // Returns list of objects upserted
    }) 

    this.accountService.delete([new Account()]).subscribe(res => {
      // Returns list of boolean values for accounts that were successfully deleted
    }) 

    /**
     *  Low level method to build a structured query
     *  @Param where clause
     *  @Param limit (optional)
     *  @Param offset (optional)
     *  @Param sort by (optional)
     *  @Param sort direction (optional)
     *  @Param ignore cache (optional default false)
     *  @Param ignore constraints (optional default false)
     */
    this.accountService.queryBuilder('ID <> NULL', 5, 2, 'Name', 'ASC', false, false).subscribe(res => {
      // Returns query results
    })
  }
}

deploy

To lint all *.ts files:

$ npm run lint

To deploy your code to your salesforce org

$ npm run deploy

Known Issues

@Angular/cli 6.0.0 Can't Resolve Stream

If you've upgraded to @angular/cli 6, and you're seeing the following error

WARNING in C:/Workspace/ngs-workspace/node_modules/xml2js/node_modules/sax/lib/sax.js
Module not found: Error: Can't resolve 'stream' in 'C:\Workspace\ngs-workspace\node_modules\xml2js\node_modules\sax\lib'

ERROR in C:/Workspace/ngs-workspace/node_modules/csv-parse/lib/index.js
Module not found: Error: Can't resolve 'stream' in 'C:\Workspace\ngs-workspace\node_modules\csv-parse\lib'
ERROR in C:/Workspace/ngs-workspace/node_modules/csv-stringify/lib/index.js
Module not found: Error: Can't resolve 'stream' in 'C:\Workspace\ngs-workspace\node_modules\csv-stringify\lib'
ERROR in C:/Workspace/ngs-workspace/node_modules/xml2js/lib/parser.js
Module not found: Error: Can't resolve 'timers' in 'C:\Workspace\ngs-workspace\node_modules\xml2js\lib'
i ｢wdm｣: Failed to compile.

Fix: Add path

Add the following to your tsconfig.app.json file under 'compilerOptions':

"paths" : {
  "jsforce" : ["./node_modules/jsforce/build/jsforce.min.js"]
  ...
}

Uncaught Error: No base href set. Please provide a value for the APP_BASE_HREF token or add a base element to the document.

In order to work on a visualforce page, your app needs to be setup to use the hash routing location strategy instead of the default

Fix: Set the useHash flag in your app-routing.module.ts file

In your app-routing.module.ts file, set the useHash flag in the RouterModule.forRoot(...) call

@NgModule({
  imports: [RouterModule.forRoot(appRoutes,  { useHash: true })],
  exports: [RouterModule]
})
export class AppRoutingModule { }

No 'Access-Control-Allow-Origin' header is present on the requested resource

Even if you enabled CORS during setup, Salesforce only supports it for certain APIs. This won't be an issue when you deploy to production. However, during development you will see this error for calls to the SOAP API. To bypass this, you must setup a proxy in @angular/cli.

Fix: Setup @angular/cli proxy

First, create a file called 'proxy.conf.json' in your root directory. This json file will look like the following:

{
  "/services/Soap/*": {
    "target": "https://my.community.url.force.com",
    "secure": false,
    "logLevel": "debug"
  }
}

Make sure you set the target to be the community url you are using.

Secondly, point your angular.json configuration to this newly created proxy configuration.

{
  ...
  "projects" : {
    ...
    "myProject" : {
      ...
      "architect" : {
        ...
        "serve" : {
          ...
          "options" : {
            ...
            "proxyConfig": "./proxy.conf.json"
          }
        }
      }
    }
  }
}

License

MIT © Christopher Moyle