Changes to Library Id's - Best Practices

[Luke 37167]

There is a change in the 4.8 beta that is being backported to 4.7 so that all users can receive the performance benefits. Library folders coming out of the api will have their Id populated with the numeric database id rather than a guid. 

Fortunately, most plugins or api users won't require any changes, but here are some best practices to follow. These changes will work with server versions 4.6+ and are both backwards and forwards compatible, so they don't require you to target a specific server version.

Server-Side Code

For your API services - make your request id's a string so that they work with both the numeric and guid id's. Then you don't need to make any calls to get guid, internal id, etc. You can get an item by Id using the string and the core will figure out how to do it. So those two lines become:

var item = _libraryManager.GetItemById(request.Id);

Or if all you need is the internal Id, and not the full object, you can save the server some work by doing:

var internalId = _libraryManager.GetInternalId(request.Id);

Additionally, If you're storing library id's in a configuration file, use strings rather than guid or long, and then use the methods I mentioned above.

This code will work with 4.6 servers and up, so if you make these changes, they will not be breaking and will not require you to target a higher nuget version.

Client-Side JavaScript

Most likely you don't' need any changes to adjust for this, but if for some reason you require access to the old guid value, then this is how you can write your code:

var libraryId = folder.Guid || folder.Id;

@roaku @TeamB @chef @Cheesegeezer @Tolriq @quickmic @pünktchen

[roaku 797]

@Luke This is affecting my plugin on the UI side.

I can resolve it for fresh installs with backend changes, but I'd like to avoid writing some sort of migration or forcing existing users to re-configure.

All I really need to do is to switch from folder.Id to folder.Guid in the javascript.

The problem is, the Guid property you described above doesn't exist in the json returned by ApiClient.getVirtualFolders(). I see Id and ItemId, but no Guid:

{
  "Name": "Collections",
  "Locations": [
    "/var/lib/emby/data/collections"
  ],
  "CollectionType": "boxsets",
  "LibraryOptions": {
    "EnableArchiveMediaFiles": false,
    "EnablePhotos": true,
    "EnableRealtimeMonitor": false,
    "EnableMarkerDetection": false,
    "EnableMarkerDetectionDuringLibraryScan": false,
    "EnableChapterImageExtraction": false,
    "ExtractChapterImagesDuringLibraryScan": false,
    "DownloadImagesInAdvance": false,
    "PathInfos": [
      {
        "Path": "/var/lib/emby/data/collections"
      }
    ],
    "IgnoreHiddenFiles": false,
    "IgnoreFileExtensions": [],
    "SaveLocalMetadata": true,
    "SaveMetadataHidden": false,
    "SaveLocalThumbnailSets": false,
    "ImportMissingEpisodes": false,
    "ImportPlaylists": true,
    "EnableAutomaticSeriesGrouping": true,
    "EnableEmbeddedTitles": false,
    "EnableAudioResume": false,
    "AutomaticRefreshIntervalDays": 0,
    "ContentType": "boxsets",
    "SeasonZeroDisplayName": "Specials",
    "Name": "Collections",
    "DisabledLocalMetadataReaders": [],
    "DisabledLyricsFetchers": [],
    "SaveLyricsWithMedia": true,
    "LyricsDownloadMaxAgeDays": 180,
    "LyricsFetcherOrder": [],
    "LyricsDownloadLanguages": [],
    "DisabledSubtitleFetchers": [],
    "SubtitleFetcherOrder": [],
    "SkipSubtitlesIfEmbeddedSubtitlesPresent": false,
    "SkipSubtitlesIfAudioTrackMatches": false,
    "SubtitleDownloadLanguages": [],
    "SubtitleDownloadMaxAgeDays": 180,
    "RequirePerfectSubtitleMatch": true,
    "SaveSubtitlesWithMedia": true,
    "ForcedSubtitlesOnly": false,
    "TypeOptions": [],
    "CollapseSingleItemFolders": true,
    "EnableAdultMetadata": false,
    "ImportCollections": false,
    "MinCollectionItems": 2,
    "MinResumePct": 5,
    "MaxResumePct": 90,
    "MinResumeDurationSeconds": 120,
    "ThumbnailImagesIntervalSeconds": -1,
    "SampleIgnoreSize": 314572800
  },
  "ItemId": "124",
  "PrimaryImageItemId": "124",
  "RefreshStatus": "Idle",
  "Type": "VirtualFolder",
  "Id": "124",
  "IsFolder": true,
  "ServerId": "616300a0b404485bab15c92d46f62838"
}

Is there some other method on ApiClient I should be calling to get the libraries with their Guid?

Edited October 14, 2022 by roaku

[roaku 797]

On 8/17/2022 at 11:28 AM, Luke said:

Client-Side JavaScript

Most likely you don't' need any changes to adjust for this, but if for some reason you require access to the old guid value, then this is how you can write your code:

var libraryId = folder.Guid || folder.Id;

 

@Luke @ebr

 

The 'Guid' property isn't present on the objects coming back from ApiClient.getVirtualFolders() in 4.7.8. What's the new 'right way' to get the Guid of a Library on the client side?

[Happy2Play 8326]

This is defective do you have /data/collections errors in your server log?

{
  "Name": "Collections",
  "Locations": [
    "/var/lib/emby/data/collections"
  ],
  "CollectionType": "boxsets",
  "LibraryOptions": {
    "EnableArchiveMediaFiles": false,
    "EnablePhotos": true,
    "EnableRealtimeMonitor": false,
    "EnableMarkerDetection": false,
    "EnableMarkerDetectionDuringLibraryScan": false,
    "EnableChapterImageExtraction": false,
    "ExtractChapterImagesDuringLibraryScan": false,
    "DownloadImagesInAdvance": false,
    "PathInfos": [
      {
        "Path": "/var/lib/emby/data/collections"
      }
    ],

This changed in 4.6 to /metadata/collections along with that options.xml and if database still has old path you have to hack deleting the library.  You have to shut down Emby, delete the collection options.xml via /var/lib/emby/root/default/collections, start Emby and you will see Collections library is now Mixed Content and you delete/remove Collections which causes a library scan and new corrected Collection is created.

So in the end it points to a failed migration when this change happened.

 

 

[roaku 797]

8 minutes ago, Happy2Play said:

This is defective do you have /data/collections errors in your server log?

{
  "Name": "Collections",
  "Locations": [
    "/var/lib/emby/data/collections"
  ],
  "CollectionType": "boxsets",
  "LibraryOptions": {
    "EnableArchiveMediaFiles": false,
    "EnablePhotos": true,
    "EnableRealtimeMonitor": false,
    "EnableMarkerDetection": false,
    "EnableMarkerDetectionDuringLibraryScan": false,
    "EnableChapterImageExtraction": false,
    "ExtractChapterImagesDuringLibraryScan": false,
    "DownloadImagesInAdvance": false,
    "PathInfos": [
      {
        "Path": "/var/lib/emby/data/collections"
      }
    ],

This changed in 4.6 to /metadata/collections along with that options.xml and if database still has old path you have to hack deleting the library.  You have to shut down Emby, delete the collection options.xml via /var/lib/emby/root/default/collections, start Emby and you will see Collections library is now Mixed Content and you delete/remove Collections which causes a library scan and new corrected Collection is created.

So in the end it points to a failed migration when this change happened.

 

 

The collections library is just one of several folders in that result set that are all missing the Guid property Luke implies should have become available after the library id backport.

The state of the collections library itself isn't relevant to the issue I need to resolve in the plugin.

Edited October 14, 2022 by roaku

[Happy2Play 8326]

I was just going off the obsolete Collection info above.

[roaku 797]

Just now, Happy2Play said:

I was just going off the obsolete Collection info above.

That's just output from a dev system with dummy data I'm pretty rough on.

[roaku 797]

Ok, I've confirmed that Guid is available through ApiClient.getItem(ApiClient._serverInfo.UserId, [Folder].Id)

@Luke It's very inconvenient that the Guid property isn't included for the folders returned through ApiClient.getVirtualFolders()

 

 

[roaku 797]

It requires an absurd stack of async/awaits and extra ajax calls per library, but I think I've got a solution that fixes the regression while supporting existing installs.

It would have been a one line fix if Guid was included with getVirtualFolders()

[Luke 37167]

HI, yes you're right. We can add Guid to this api. It will be in the next beta server. We'll also be doing a 4.7.9 maintenance release soon and it will be included in that as well. Thanks.

[Jogex 0]

Hey, guys!

So this change broke my API integrations because the Users/{userId}/Policy endpoint still uses the GUID for EnabledFolders and ExcludedSubFolders.
Do I need to worry about this also changing suddenly down the line?

[Luke 37167]

3 hours ago, Jogex said:

Hey, guys!

So this change broke my API integrations because the Users/{userId}/Policy endpoint still uses the GUID for EnabledFolders and ExcludedSubFolders.
Do I need to worry about this also changing suddenly down the line?

Well for now use the guid property that I mentioned above.

By the time 4.8 releases, those values are probably going to be moved out of the policy object altogether though because they're moving into the database. They'll still be reachable via API of course but I'm not sure yet if it will be the same way or not.