Difference between revisions of "Directory Modules"

Latest revision as of 09:55, 19 July 2021

This is the resource to add your local directory to the Advice Local network. There are 2 different modules that need to be submitted for review which are the "scan" and "submit" module. Both are documented below.

Module Structure

Both the scan and submit modules are currently AWS Lambda modules. Although Lambda supports several different languages, Advice Local currently only supports Node.js. The version of Node.js is 10.x. Both modules are very simple in the sense that there is no API, no database to worry about, no scaling or infrastructure considerations. The flow is data in, data out, and anything that happens within is at the discretion of the developer.

Client Object

The object passed into the module is the only data provided to do any work associated with scanning or submitting. There is no database or API access given to the Advice Local API.

  client = {
    id: {
        type: 'number',
        required: true
    },
    businessName: {
      type: 'string',
      required: true,
    },
    city: {
      type: 'string',
      required: true,
    },
    street1: {
      type: 'string',
    },
    street2: {
      type: 'string',
    },
    state: {
      type: 'string',
      required: true,
    },
    postal: {
      type: 'string',
      required: true,
    },
    country: {
      type: 'string',
      defaultsTo: 'US',
      enum: [
        'US',
        'GB',
        'CA',
        'AU',
        'BS',
        'DE',
        'NZ',
        'CR',
      ],
    },
    website: {
      type: 'string',
    },
    hours: {
      type: 'json',
    },
    hoursSpecial: {
      type: 'json',
    },
    description: {
      type: 'text',
    },
    hide: {
      type: 'boolean',
      defaultsTo: false,
    },
    phone: {
      type: 'string',
    },
    fax: {
      type: 'string',
    },
    email: {
      type: 'string',
    },
    owner: {
      type: 'string',
    },
    payment: {
      type: 'string',
    },
    paymentObject: {
      type: 'json',
    },
    services: {
      type: 'string',
    },
    license: {
      type: 'string',
    },
    isActive: {
      type: 'boolean',
      defaultsTo: true,
    },
    isDeleted: {
      type: 'boolean',
      defaultsTo: false,
    },
    LAT: {
      type: 'float',
    },
    LON: {
      type: 'float',
    },
    category: {
      type: 'text',
    },
    keywords: {
      collection: 'keyword',
      via: 'client',
    },
    submissions: {
      type: 'json',
    },

    custom1: {
      type: 'string',
      index: true,
    },
    custom2: {
      type: 'string',
      index: true,
    },
    custom3: {
      type: 'string',
      index: true,
    },
    custom4: {
      type: 'string',
      index: true,
    },
    custom5: {
      type: 'string',
      index: true,
    },
    extra: {
      type: 'json',
    }
);

Scan

Submit

In addition to the client data, there are a few properties sent.

Action Property

The property is called "action" and can have a value of "submit", "update", "link", or "deactivate".

• submit - the system is requesting this business be submitted to the directory
• update - the business should have already been submitted before, perform a lookup and update
• deactivate - the business no longer wishes to be managed by the system
• link - providing a link tot he updated business only

Submissions Property

This property is called submissions and has information about other directories that this business has been submitted to. This object usually contains IDs of other listings on other directories as well which is useful if there needs to be any cross referencing of data. For example, here is what a submission object might look like:

{
    submissions: {
        foursquare: {
            id: 139891984012
        },
        yellowpages: {
            LID: "ABAD12980F8"
        }
    }
}

Returning Results

After the module is done processing the appropriate action, it MUST return an object in the following format:

{
    error: "There was some error",
    success: "true" // "false",
    url: "http://www.directory.com/CA/NewportBeach/perros_bakery",
    action: "submit"
    request: {},
    response: {}
    save: {}
}

The error can be null if success='true', otherwise, it is expected that the module pass back a reason for the submission to fail. Success is a true/false string. The url field should be passed back indicating what url was worked on (if submissions are asynchronous then this can be blank). The action usually corresponds to the action provided inbound into the module, however is not always the same. For example, the system might request the action of "submit", however, if some logic within the module determines that the business already exists in the directory, then the module should update the information and pass back the action "update".

The request and response objects are really for debugging purposes. You can pass back any information you see fit in order to later request logs from and debug.

Saving Data

Submission modules are stateless and since there is no access to any APIs or database to store information, the "save" object is used to return information back to the system for later use. For example, unique IDs that are created, statuses that need to be retained, tokens to be used later, etc. All information passed back in the save object will be merged into the "submissions" object described above. The property within the submissions object that this is saved to depends on the name of the published lambda module itself. So if the submission module is called "acmedirectory" (the convention for naming is all lowercase with no spaces), then you can expect your data to be returned upon the next invocation of the module as:

{ submissions:
    {
        "acmedirectory": {
            "id": "12345",
            "status": "approved"
        }
    }
}

Keep in mind this is just an example. You can pass back any valid JSON object that you want. Properties are always merged so you do not have to include an entire object with your additions. The only time you will lose data is if you return an object with the same property name and a different value.