User Generated Content (UGC)

User Generated Content (UGC) is a separate Agility service for storing content that your website's visitors create: form submissions, comments, ratings, likes and votes, uploaded files, and website user profiles. It's separate from the content your editors manage in Agility, and it has its own API at ugc.agilitycms.com.

Most websites used UGC for one thing: saving form submissions, like contact forms, feedback forms and sign-ups.

How UGC works

Record types and records

UGC stores records. Each record belongs to a record type, which defines its fields, much like a content model does for regular content. A contact form, for example, would have a ContactSubmission record type with fields for name, email and message.

Every record has a state: New, Published, Draft, AwaitingReview, Escalated, Declined, Processing, Error or Deleted. This is how moderation works. See Record type settings.

Records can also carry comments, feedback (ratings, likes, votes and approve/disapprove) and files.

Access keys and the access hash

Each website gets a UGC Access Key and Secret Key. If you don't have yours, contact support@agilitycms.com.

Calls from the browser are signed with an access hash, which your server computes so the Secret Key never reaches the browser. The hash is the SHA-1 of these values, joined with dots:

[seconds].[profileRecordID].[secretKey].[accessKey].[random]

• seconds: seconds elapsed since January 1, 2001
• profileRecordID: the signed-in website user's profile record ID, or -1 for an anonymous visitor
• random: a random number from 1 to 1000

Your server puts the result, without the Secret Key, into a global _AgilityUGCSettings object on the page:

var _AgilityUGCSettings = {
  Url: "https://ugc.agilitycms.com/Agility-UGC-API-JSONP.svc",
  AccessKey: "YOUR-ACCESS-KEY",
  Seconds: "567353588",
  RandomNumber: "205",
  ProfileRecordID: "-1",
  AccessHash: "THE-SHA1-HASH"
};

The JavaScript SDK

The agility-ugc package is a browser-only client for the UGC API. It picks up _AgilityUGCSettings automatically.

npm install agility-ugc

Saving and searching records looks like this:

import ugcClient from "agility-ugc";

const searchArg = new ugcClient.SearchArg();
searchArg.RecordTypeName = "ContactSubmission";
searchArg.PageSize = 10;
searchArg.RecordOffset = 0;

ugcClient.SearchRecords(searchArg, (data) => {
  if (data.ResponseType !== ugcClient.ResponseType.OK) {
    console.error(data.Message);
    return;
  }
  const { Records, TotalRecords } = data.ResponseData;
});

The main methods are:

Task	Methods
Records	SaveRecord, GetRecord, SearchRecords, DeleteRecord, SetRecordState
Record types	GetAllRecordTypes, GetRecordTypeByName, SaveRecordType
Comments and feedback	SearchComments, SaveRating, SaveLike, SaveVote, GetFeedbackAggregate
Files	GetUGCUploadForm, UploadFile, DeleteFile
Website users	Authenticate, IsAuthenticated, Logout, ChangePassword, RetrievePassword

Every method is asynchronous and takes a callback. Check data.ResponseType before you use data.ResponseData.

Record type settings

You manage record types in the classic Content Manager, under Settings → UGC Definitions. These settings decide what happens to a new record:

Setting	What it does
Enable Publishing Workflow	Lets records of this type be published. When it's off, records are stored but never published. That's usually what a contact form wants.
Requires Moderation	New records wait for a moderator to publish them. When it's off, they publish as soon as they're saved.
Enable Draft Mode	New records start as drafts.

Your settings	A new record starts as
Publishing workflow off	New
Requires Moderation on	New
Requires Moderation off	Published
Draft mode on	Draft

Moderators publish or decline records in the Content Manager's UGC section. To get an email when new records arrive, subscribe on the record type's Alerts tab.

Saving a record

Pass the record type's name, plus one property per field. Use each field's reference name, which is case-sensitive:

const record = {
  RecordTypeName: "ContactSubmission",
  FirstName: "Ada",
  LastName: "Lovelace",
  Email: "ada@example.com",
  Message: "Can you send me a quote?",
};

ugcClient.SaveRecord(record, (data) => {
  if (data.ResponseType !== ugcClient.ResponseType.OK) {
    console.error(data.Message);
    return;
  }
});

Nothing is saved if a property doesn't match a field on the record type, or if a required field is missing. data.Message names the field.

Troubleshooting submissions

Submissions stopped working after we moved to a new domain. UGC only accepts submissions from domains on your website's allowed list. Wildcard entries don't work, so every domain, including www and other subdomains, has to be listed separately. Contact support@agilitycms.com with the exact domains to add.

Submissions are saved, but the notification email doesn't arrive. For a Form Builder form, check these:

• The from address must be an @agilitycms.com address. Emails from any other domain, including your own, aren't sent.
• The email-to address, subject and body must all be filled in.
• Every field on the record type must still be on the form. A field you removed or renamed on the form, but left on the record type, stops the email going out. The submission is still saved.

The form says it worked, but the submission isn't on my site. It's probably waiting for a moderator, or the record type doesn't publish records at all. Look for it in the Content Manager's UGC section. Check Record type settings.

The save fails and the message names a field. A field in your form doesn't match the record type. Names are case-sensitive, and a named submit button counts as a field. Compare your form with the record type's fields in Settings → UGC Definitions.

A new submission or a settings change doesn't show up right away. Changes can take a few minutes to appear. Wait, then check again.

What to use instead

If you're using UGC for forms, or about to, there's a better option today. Let a form provider handle the form, or send submissions straight to the system your team already works in. You get spam protection, notifications, reporting and integrations without having to build them.

A form provider

Build the form in a form tool, and let editors place it on any page in Agility with an app:

• Formstack
• Typeform

Using a different form provider? Most of them give you an embed code or a form ID, so it's easy to hook up with a custom field or a small app (see Connecting something else).

Your CRM, directly

If submissions end up in your CRM anyway, skip the middle step and send them there:

• HubSpot: build the form in HubSpot and pick it in Agility.
• Salesforce Web-to-Lead: turn a Salesforce web-to-lead form into a form on your site.
• Salesforce Sales Cloud: create Salesforce contacts from your own form through a small backend.

The same pattern works for any CRM with an API. Post the form to a server route on your website, and have the route call the CRM.

Connecting something else

If there's no app for your tool yet, you can build one. Apps run inside Agility and can add custom fields, so editors pick a form from a list instead of pasting IDs. See Creating Apps for Agility. Need to react when content changes instead? Use webhooks.

Moving off UGC

You don't have to move. UGC is still supported. When you're ready:

1. Pick where new submissions go: a form provider or your CRM, from the options above.
2. Rebuild the form there, and swap it onto your pages in Agility.
3. Keep what you already collected. Read your existing records with SearchRecords and import them into the new system, if you still need them.
4. Remove the UGC code from your website, including the server code that computes the access hash.

Have questions about your UGC setup? Contact support@agilitycms.com.